airflow-core/docs/security/jwt_token_authentication.rst
.. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
.. http://www.apache.org/licenses/LICENSE-2.0
.. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
This document describes how JWT (JSON Web Token) authentication works in Apache Airflow for both the public REST API (Core API) and the internal Execution API used by workers.
.. contents:: :local: :depth: 2
Airflow uses JWT tokens as the primary authentication mechanism for its APIs. There are two distinct JWT authentication flows:
Both flows share the same underlying JWT infrastructure (JWTGenerator and JWTValidator
classes in airflow.api_fastapi.auth.tokens) but differ in audience, token lifetime, subject
claims, and scope semantics.
Airflow supports two mutually exclusive signing modes:
Symmetric (shared secret)
Uses a pre-shared secret key ([api_auth] jwt_secret) with the HS512 algorithm.
All components that generate or validate tokens must share the same secret. If no secret
is configured, Airflow auto-generates a random 16-byte key at startup — but this key is
ephemeral and different across processes, which will cause authentication failures in
multi-component deployments. Deployment Managers must explicitly configure this value.
Asymmetric (public/private key pair)
Uses a PEM-encoded private key ([api_auth] jwt_private_key_path) for signing and
the corresponding public key for validation. Supported algorithms: RS256 (RSA) and
EdDSA (Ed25519). The algorithm is auto-detected from the key type when
[api_auth] jwt_algorithm is set to GUESS (the default).
Validation can use either:
[api_auth] trusted_jwks_url
(local file or remote HTTP/HTTPS URL, polled periodically for updates).trusted_jwks_url is not set).Token acquisition ^^^^^^^^^^^^^^^^^
POST request to /auth/token with credentials (e.g., username
and password in JSON body).JWTGenerator.generate().access_token.For UI-based authentication, the token is stored in a secure, HTTP-only cookie (_token)
with SameSite=Lax.
The CLI uses a separate endpoint (/auth/token/cli) with a different (shorter) expiration
time.
Token structure (REST API) ^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table:: :header-rows: 1 :widths: 15 85
jtiiss[api_auth] jwt_issuer).aud[api_auth] jwt_audience).subiatnbfiat).expiat + jwt_expiration_time).Token validation (REST API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^
On each API request, the token is extracted in this order of precedence:
Authorization: Bearer <token> header._token cookie.The JWTValidator verifies the signature, expiry (exp), not-before (nbf),
issued-at (iat), audience, and issuer claims. A configurable leeway
([api_auth] jwt_leeway, default 10 seconds) accounts for clock skew.
Token revocation (REST API only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Token revocation applies only to REST API and UI tokens — it is not used for Execution API tokens issued to workers.
Revoked tokens are tracked in the revoked_token database table by their jti claim.
On logout or explicit revocation, the token's jti and exp are inserted into this
table. Expired entries are automatically cleaned up at a cadence of 2× jwt_expiration_time.
Token refresh (REST API) ^^^^^^^^^^^^^^^^^^^^^^^^
The JWTRefreshMiddleware runs on UI requests. When the middleware detects that the
current token's _token cookie is approaching expiry, it calls
auth_manager.refresh_user() to generate a new token and sets it as the updated cookie.
Default timings (REST API) ^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table:: :header-rows: 1 :widths: 50 50
[api_auth] jwt_expiration_time[api_auth] jwt_cli_expiration_time[api_auth] jwt_leewayThe Execution API is an API used for use by Airflow itself (not third party callers) to report and set task state transitions, send heartbeats, and to retrieve connections, variables, and XComs at task runtime, trigger execution and Dag parsing.
Token generation (Execution API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
jwt_generator property creates a JWTGenerator configured with the [execution_api] settings.sub (subject) claim is set to the task instance UUID.BaseWorkloadSchema.token field)
that is sent to the worker process.Token structure (Execution API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table:: :header-rows: 1 :widths: 15 85
jtiiss[api_auth] jwt_issuer).aud[execution_api] jwt_audience, default: urn:airflow.apache.org:task).subscope"execution" or "workload".iatnbfexpiat + [execution_api] jwt_expiration_time).Token scopes (Execution API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Execution API defines two token scopes:
workload
A restricted scope accepted only on endpoints that explicitly opt in via
Security(require_auth, scopes=["token:workload"]). Used for endpoints that
manage task state transitions.
execution Accepted by all Execution API endpoints. This is the standard scope for worker communication and allows access
Tokens without a scope claim default to "execution" for backwards compatibility.
Token delivery to workers ^^^^^^^^^^^^^^^^^^^^^^^^^
The token flows through the execution stack as follows:
execute_workload() function reads the workload JSON and extracts the token.supervise() function receives the token and creates an httpx.Client instance
with BearerAuth(token) for all Execution API HTTP requests.Authorization: Bearer <token> header of every request.Token validation (Execution API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The JWTBearer security dependency validates the token once per request:
Authorization: Bearer header.JWTValidator.exp, iat, aud — nbf and iss if configured).scope claim to "execution" if absent.TIToken object with the task instance ID and claims.Route-level enforcement is handled by require_auth:
scope against the route's allowed_token_types (precomputed
by ExecutionAPIRoute from token:* Security scopes at route registration time).ti:self scope — verifies that the token's sub claim matches the
{task_instance_id} path parameter, preventing a worker from accessing another task's
endpoints.Token refresh (Execution API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The JWTReissueMiddleware automatically refreshes valid tokens that are approaching expiry:
scope and sub).Refreshed-API-Token response header._update_auth() hook detects this header and transparently updates
the BearerAuth instance for subsequent requests.This mechanism ensures long-running tasks do not lose API access due to token expiry, without requiring the worker to re-authenticate.
No token revocation (Execution API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Execution API tokens are not subject to revocation. They are short-lived (default 10 minutes)
and automatically refreshed by the JWTReissueMiddleware, so revocation is not part of the
Execution API security model. Once an Execution API token is issued to a worker, it remains
valid until it expires.
Default timings (Execution API) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. list-table:: :header-rows: 1 :widths: 50 50
[execution_api] jwt_expiration_time[execution_api] jwt_audienceurn:airflow.apache.org:taskThe Dag File Processor and Triggerer are internal Airflow components that also
interact with the Execution API, but they do so via an in-process transport
(InProcessExecutionAPI) rather than over the network. This in-process API:
TIToken with the "execution" scope, effectively bypassing
token validation.Airflow implements software guards that prevent accidental direct database access from Dag
author code in these components. However, because the child processes that parse Dag files and
execute trigger code run as the same Unix user as their parent processes, these guards do
not protect against intentional access. A deliberately malicious Dag author can potentially
retrieve the parent process's database credentials (via /proc/<PID>/environ, configuration
files, or secrets manager access) and gain full read/write access to the metadata database and
all Execution API operations — without needing a valid JWT token.
This is in contrast to workers/task execution, where the isolation is implemented ad deployment level - where sensitive configuration of database credentials is not available to Airflow processes because they are not set in their deployment configuration at all, and communicate exclusively through the Execution API.
In the default deployment, a single Dag File Processor instance parses Dag files for all teams and a single Triggerer instance handles all triggers across all teams. This means that Dag author code from different teams executes within the same process, with potentially shared access to the in-process Execution API and the metadata database.
For multi-team deployments that require isolation, Deployment Managers must run separate Dag File Processor and Triggerer instances per team as a deployment-level measure — Airflow does not provide built-in support for per-team DFP or Triggerer instances. Even with separate instances, each retains the same Unix user as the parent process. To prevent credential retrieval, Deployment Managers must implement Unix user-level isolation (running child processes as a different, low-privilege user) or network-level restrictions.
See :doc:/security/security_model for the full security implications, deployment hardening
guidance, and the planned strategic and tactical improvements.
For a detailed discussion of workload isolation protections, current limitations, and planned
improvements, see :ref:workload-isolation.
All JWT-related configuration parameters:
.. list-table:: :header-rows: 1 :widths: 40 15 45
[api_auth] jwt_secretjwt_private_key_path.[api_auth] jwt_private_key_pathRSA or Ed25519). Mutually exclusive with jwt_secret.[api_auth] jwt_algorithmGUESSHS512 for symmetric, RS256 for RSA, EdDSA for Ed25519.[api_auth] jwt_kidRFC 7638 thumbprint)[api_auth] jwt_issueriss). Recommended to be unique per deployment.[api_auth] jwt_audienceaud) for REST API tokens.[api_auth] jwt_expiration_time[api_auth] jwt_cli_expiration_time[api_auth] jwt_leeway[api_auth] trusted_jwks_urljwt_secret.[execution_api] jwt_expiration_time[execution_api] jwt_audienceurn:airflow.apache.org:task.. important::
Time synchronization across all Airflow components is critical. Use NTP (e.g., ntpd or
chrony) to keep clocks in sync. Clock skew beyond the configured jwt_leeway will cause
authentication failures.