Docs: refresh JWT and security model for v3.2 with mermaid diagrams

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.

[potiuk]

Catch up the public security documentation to match the security-relevant
changes flowing into the 3.2 release branch. Adds six mermaid diagrams
and re-aligns prose with the current code.

What changed in the docs

airflow-core/docs/security/jwt_token_authentication.rst:

• 4 mermaid diagrams: components-and-flows overview; symmetric vs
  asymmetric signing; two-token sequence (Scheduler → executor queue →
  worker /run → refreshed execution token); request-time validation
  pipeline (signature → standard claims → TIClaims schema →
  require_auth scope → ti:self).
• Documents typed TIClaims Pydantic claims validation (Validate task identity token claims with a typed schema #63604).
• Documents that /auth/logout now invokes auth_manager.revoke_token()
  unconditionally, even when the auth manager redirects to an external
  IdP logout URL (Revoke JWT on /auth/logout regardless of auth manager logout URL #67289).

airflow-core/docs/security/security_model.rst:

• 2 mermaid diagrams: component trust boundaries (control plane vs
  worker plane, DFP/Triggerer's in-process Execution API bypass);
  per-component credential-distribution matrix for sensitive values.
• New "Defense in depth at the router level" subsection documenting
  router-level Depends(get_user) on authenticated_router and
  ui_router (Default-deny auth at the API and UI router level #66505).
• Notes what the Execution API does enforce beyond ti:self:
  ExecutionAPISecretsBackend raises PermissionError on 401/403
  instead of letting the dispatcher fall through to a less-restrictive
  backend (Refuse secrets-backend fallback on Execution-API authz deny #66575); tightened deserialization allowlist regex requires a
  full-string match (Tighten deserialization allowlist regex to require full-string match #66499); typed claims schema rejects non-UUID
  sub or unknown scope.

Tooling change

Registers sphinxcontrib-mermaid>=1.0.0 as a new dependency in
devel-common[docs] and adds sphinxcontrib.mermaid to
BASIC_SPHINX_EXTENSIONS so every Airflow Sphinx build (core,
providers, chart, docker-stack) can use .. mermaid:: directives.
uv.lock is regenerated.

Verification

• breeze build-docs --package-filter apache-airflow →
  "Documentation build is successful", 0 build errors, 0 spelling errors.
• All six mermaid containers render in the produced HTML.
• prek run --from-ref upstream/main --stage pre-commit and
  --stage manual both pass.

---

Was generative AI tooling used to co-author this PR?

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[potiuk]

cc: @ashb@anishgirianish@kaxil@amoghrajesh@pierrejeambrun@vincbeck

[potiuk]

Also cc: @vatsrahul1001 -> we should include it in rc2

[potiuk]

Below are the six mermaid diagrams introduced in this PR (updated for higher contrast and an easier-to-read credential matrix), rendered inline via GitHub's native mermaid support. They are identical to what breeze build-docs produces in the published HTML.

---

jwt_token_authentication.rst — overview of components and flows

flowchart LR
subgraph Clients
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph Internal["Internal Airflow components"]
WORKER[Worker / Task]
DFP[Dag File Processor]
TRG[Triggerer]
end
APISVR[API Server]
EXECAPI[Execution API]
UI -->|JWT cookie / Bearer| APISVR
CLI -->|Bearer| APISVR
EXT -->|Bearer| APISVR
WORKER -->|Bearer<br/>workload &rarr; execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WORKER,DFP,TRG internal

Loading

---

jwt_token_authentication.rst — symmetric vs asymmetric signing

flowchart TB
subgraph Sym["Symmetric (HS512)"]
direction LR
S1[Scheduler / API Server]
S2[Shared secret<br/>jwt_secret]
S3[Token validator]
S1 -->|sign| S2 -->|same secret<br/>also validates| S3
end
subgraph Asym["Asymmetric (RS256 / EdDSA)"]
direction LR
A1[Scheduler / API Server]
A2[Private key<br/>jwt_private_key_path]
A3[Public key /<br/>JWKS endpoint]
A4[Token validator]
A1 -->|sign| A2
A2 -. derives or<br/>publishes .-> A3
A3 -->|verify only| A4
end
classDef secret fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pub fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class S2 secret
class A2 secret
class A3 pub

Loading

---

jwt_token_authentication.rst — two-token sequence (workload → execution)

sequenceDiagram
autonumber
participant SCH as Scheduler
participant EXE as Executor<br/>(Celery / K8s / Local)
participant WRK as Worker
participant API as Execution API
Note over SCH: Task ready to dispatch
SCH->>SCH: generate workload token<br/>scope=workload<br/>exp = task_queued_timeout
SCH->>EXE: workload JSON<br/>(includes token)
Note over EXE: Task waits in queue<br/>(can be minutes)
EXE->>WRK: dispatch (workload JSON)
WRK->>API: POST /run<br/>Bearer: workload token
Note over API: validates workload scope<br/>checks TI in QUEUED/RESTARTING<br/>409 if not
API-->>WRK: 200 OK<br/>Refreshed-API-Token: execution token<br/>(scope=execution, ~10 min)
WRK->>WRK: BearerAuth swaps to<br/>execution token
loop For all subsequent calls (heartbeats, XComs, ...)
WRK->>API: Bearer: execution token
alt token expiring (less than 20% left)
API-->>WRK: 200 OK<br/>Refreshed-API-Token: new execution token
WRK->>WRK: BearerAuth swaps again
end
end

Loading

---

jwt_token_authentication.rst — Execution API request-time validation pipeline

flowchart TD
REQ([Incoming request<br/>Authorization: Bearer ...])
REQ --> CACHE{Cached on<br/>request.scope?}
CACHE -->|yes| RET([Return cached TIToken])
CACHE -->|no| SIG[JWTValidator:<br/>verify signature]
SIG -->|fail| F1([403 Forbidden])
SIG -->|ok| STD[Verify exp / iat / nbf<br/>aud / iss]
STD -->|fail| F1
STD -->|ok| SCOPE[Default scope to<br/>'execution' if absent]
SCOPE --> SCHEMA[TIClaims:<br/>typed Pydantic schema]
SCHEMA -->|ValidationError| F1
SCHEMA -->|ok| TYP{require_auth:<br/>scope in<br/>route.allowed_token_types?}
TYP -->|no| F1
TYP -->|yes| SELF{ti:self scope<br/>declared?}
SELF -->|no| OK([Return TIToken])
SELF -->|yes| MATCH{token.sub ==<br/>task_instance_id?}
MATCH -->|no| F1
MATCH -->|yes| OK
classDef fail fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef pass fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
class F1 fail
class OK,RET pass

Loading

---

security_model.rst — component trust boundaries

flowchart LR
subgraph users["Users (untrusted by default)"]
UI[UI / browser]
CLI[CLI]
EXT[External REST clients]
end
subgraph dataplane["Worker plane (no metadata DB access)"]
WRK[Worker / Task]
end
subgraph controlplane["Control plane (metadata DB access)"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
end
DB[(Metadata DB)]
UI -->|JWT| APISVR
CLI -->|JWT| APISVR
EXT -->|JWT| APISVR
WRK -->|JWT<br/>Execution API| APISVR
APISVR -. SQL .-> DB
SCH -. SQL .-> DB
DFP -. SQL .-> DB
TRG -. SQL .-> DB
DFP -. in-process<br/>JWT bypassed .-> APISVR
TRG -. in-process<br/>JWT bypassed .-> APISVR
classDef untrusted fill:#ffcdd2,stroke:#c62828,stroke-width:2px,color:#000
classDef trusted fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef data fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data

Loading

---

security_model.rst — credential-distribution (least → most privileged)

flowchart LR
subgraph WRK["Worker (least privileged)"]
direction TB
W1[Fernet key]
W2[Worker secrets backend credentials]
W3[Remote log handler kwargs]
end
subgraph TRG["Triggerer"]
direction TB
T1[DB connection]
T2[Fernet key]
T3[Non-worker secrets backend credentials]
T4[Remote log handler kwargs]
end
subgraph DFP["Dag File Processor"]
direction TB
D1[DB connection]
D2[Fernet key]
D3[Non-worker secrets backend credentials]
end
subgraph SCH["Scheduler"]
direction TB
S1[DB connection]
S2[JWT signing key]
S3[Fernet key]
S4[Non-worker secrets backend credentials]
S5[Remote log handler kwargs]
end
subgraph API["API Server (most privileged)"]
direction TB
A1[DB connection]
A2[JWT signing key]
A3[Fernet key]
end
classDef wrk fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px,color:#000
classDef ctrl fill:#bbdefb,stroke:#1565c0,stroke-width:2px,color:#000
class WRK wrk
class API,SCH,DFP,TRG ctrl

Loading

The doc also includes an explicit ✓/— table for true matrix lookup (which secret does which component need?) — see the rst source.

---

Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting

[github-actions]

Backport failed to create: v3-2-test. View the failure log Run details

Note: As of Merging PRs targeted for Airflow 3.X
the committer who merges the PR is responsible for backporting the PRs that are bug fixes (generally speaking) to the maintenance branches.

In matter of doubt please ask in #release-management Slack channel.

Status	Branch	Result
❌	v3-2-test

You can attempt to backport this manually by running:

cherry_picker 0a506b1 v3-2-test

This should apply the commit to the v3-2-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

If you don't have cherry-picker installed, see the installation guide.