This is an automated email from the ASF dual-hosted git repository.
bugraoz pushed a commit to branch v3-1-test
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/v3-1-test by this push:
new cead7c66dd5 [v3-1-test] Add Refresh Token logic to auth manager docs
(#54196) (#59482)
cead7c66dd5 is described below
commit cead7c66dd54c249eef3fc5afe32805633050f7e
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Mon Dec 15 23:01:54 2025 +0100
[v3-1-test] Add Refresh Token logic to auth manager docs (#54196) (#59482)
* Update httponly logic in docs
(cherry picked from commit 1ba1732caf0910bf32acc32db1e32e82e26144a6)
Co-authored-by: Bugra Ozturk <[email protected]>
---
.../docs/core-concepts/auth-manager/index.rst | 22 ++++++++++++++++++++--
1 file changed, 20 insertions(+), 2 deletions(-)
diff --git a/airflow-core/docs/core-concepts/auth-manager/index.rst
b/airflow-core/docs/core-concepts/auth-manager/index.rst
index 5ace2150eb8..258b9aae362 100644
--- a/airflow-core/docs/core-concepts/auth-manager/index.rst
+++ b/airflow-core/docs/core-concepts/auth-manager/index.rst
@@ -170,8 +170,26 @@ cookie named ``_token`` before redirecting to the Airflow
UI. The Airflow UI wil
return response
.. note::
- Do not set the cookie parameter ``httponly`` to ``True``. Airflow UI needs
to access the JWT token from the cookie.
-
+ Ensure that the cookie parameter ``httponly`` is set to ``True``. The UI
does not manage the token.
+
+Refreshing JWT Token
+''''''''''''''''''''
+Refreshing token is optional feature and its availability depends on the
specific implementation of the auth manager.
+The auth manager is responsible for refreshing the JWT token when it expires.
+The Airflow API uses middleware that intercepts every request and checks the
validity of the JWT token.
+Token communication is handled through ``httponly`` cookies to improve
security.
+When the token expires, the `JWTRefreshMiddleware
<https://github.com/apache/airflow/blob/3.1.5/airflow-core/src/airflow/api_fastapi/auth/middlewares/refresh_token.py>`_
middleware calls the auth manager's ``refresh_user`` method to obtain a new
token.
+
+
+To support token refresh operations, the auth manager must implement the
``refresh_user`` method.
+This method receives an expired token and must return a new valid token.
+User information is extracted from the expired token and used to generate a
fresh token.
+
+An example implementation of ``refresh_user`` could be:
+`KeycloakAuthManager::refresh_user
<https://github.com/apache/airflow/blob/3.1.5/providers/keycloak/src/airflow/providers/keycloak/auth_manager/keycloak_auth_manager.py#L113-L121>`_
+User information is derived from the ``BaseUser`` instance.
+It is important that the user object contains all the fields required to
refresh the token. An example user class could be:
+`KeycloakAuthManagerUser(BaseUser)
<https://github.com/apache/airflow/blob/3.1.5/providers/keycloak/src/airflow/providers/keycloak/auth_manager/user.pys>`_.
Optional methods recommended to override for optimization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
