You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "potiuk (via GitHub)" <gi...@apache.org> on 2026/05/24 20:13:41 UTC
[PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
potiuk opened a new pull request, #67435:
URL: https://github.com/apache/airflow/pull/67435
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 (#63604).
- Documents that `/auth/logout` now invokes `auth_manager.revoke_token()`
unconditionally, even when the auth manager redirects to an external
IdP 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` (#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 (#66575); tightened deserialization allowlist regex requires a
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?
- [X] Yes — Claude Code (Opus 4.7)
Generated-by: Claude Code (Opus 4.7) following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
Posted by "github-actions[bot] (via GitHub)" <gi...@apache.org>.
github-actions[bot] commented on PR #67435:
URL: https://github.com/apache/airflow/pull/67435#issuecomment-4533618448
### Backport failed to create: v3-2-test. View the failure log <a href='https://github.com/apache/airflow/actions/runs/26396320002'> Run details </a>
Note: As of [Merging PRs targeted for Airflow 3.X](https://github.com/apache/airflow/blob/main/dev/README_AIRFLOW3_DEV.md#merging-prs-targeted-for-airflow-3x)
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](https://apache-airflow.slack.com/archives/C03G9H97MM2) Slack channel.
<table>
<tr>
<th>Status</th>
<th>Branch</th>
<th>Result</th>
</tr>
<tr>
<td>❌</td>
<td>v3-2-test</td>
<td><a href="https://github.com/apache/airflow/commit/0a506b18b9dd1e86df52302677c41f0c078f8de2"><img src='https://img.shields.io/badge/Commit-0a506b1-red' alt='Commit Link'></a></td>
</tr>
</table>
You can attempt to backport this manually by running:
```bash
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:
```bash
cherry_picker --continue
```
If you don't have cherry-picker installed, see the [installation guide](https://github.com/apache/airflow/blob/main/dev/README.md#how-to-backport-pr-with-cherry-picker-cli).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on PR #67435:
URL: https://github.com/apache/airflow/pull/67435#issuecomment-4529856419
cc: @ashb @anishgirianish @kaxil @amoghrajesh @pierrejeambrun @vincbeck
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on PR #67435:
URL: https://github.com/apache/airflow/pull/67435#issuecomment-4529857282
Also cc: @vatsrahul1001 -> we should include it in rc2
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on PR #67435:
URL: https://github.com/apache/airflow/pull/67435#issuecomment-4529901356
Below are the six mermaid diagrams introduced in this PR, 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
```mermaid
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 → execution| EXECAPI
DFP -. in-process<br/>JWT bypassed .-> EXECAPI
TRG -. in-process<br/>JWT bypassed .-> EXECAPI
classDef internal fill:#eef,stroke:#446
class WORKER,DFP,TRG internal
```
---
### `jwt_token_authentication.rst` — symmetric vs asymmetric signing
```mermaid
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:#fee,stroke:#a33
classDef pub fill:#efe,stroke:#3a3
class S2 secret
class A2 secret
class A3 pub
```
---
### `jwt_token_authentication.rst` — two-token sequence (workload → execution)
```mermaid
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
```
---
### `jwt_token_authentication.rst` — Execution API request-time validation pipeline
```mermaid
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:#fee,stroke:#a33
classDef pass fill:#efe,stroke:#3a3
class F1 fail
class OK,RET pass
```
---
### `security_model.rst` — component trust boundaries
```mermaid
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:#fee,stroke:#a33
classDef trusted fill:#efe,stroke:#3a3
classDef data fill:#eef,stroke:#446
class UI,CLI,EXT,WRK untrusted
class APISVR,SCH,DFP,TRG trusted
class DB data
```
---
### `security_model.rst` — credential-distribution matrix
```mermaid
flowchart LR
subgraph secrets["Sensitive values"]
DBC[DB connection<br/>SQL_ALCHEMY_CONN]
JWT[JWT signing key<br/>jwt_secret /<br/>jwt_private_key_path]
FERN[Fernet key]
SB_CFG[Secrets backend<br/>credentials<br/>non-worker]
SB_WRK[Secrets backend<br/>credentials<br/>worker]
REMLOG[Remote log<br/>handler kwargs]
end
subgraph components["Components"]
APISVR[API Server]
SCH[Scheduler]
DFP[Dag File Processor]
TRG[Triggerer]
WRK[Worker]
end
DBC --> APISVR
DBC --> SCH
DBC --> DFP
DBC --> TRG
JWT --> APISVR
JWT --> SCH
FERN --> APISVR
FERN --> SCH
FERN --> DFP
FERN --> TRG
FERN --> WRK
SB_CFG --> SCH
SB_CFG --> DFP
SB_CFG --> TRG
SB_WRK --> WRK
REMLOG --> SCH
REMLOG --> TRG
REMLOG --> WRK
classDef worker fill:#efe,stroke:#3a3
classDef control fill:#eef,stroke:#446
class WRK worker
class APISVR,SCH,DFP,TRG control
```
---
Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
Posted by "kaxil (via GitHub)" <gi...@apache.org>.
kaxil commented on code in PR #67435:
URL: https://github.com/apache/airflow/pull/67435#discussion_r3295281300
##########
airflow-core/docs/security/jwt_token_authentication.rst:
##########
@@ -242,6 +308,37 @@ The token flows through the execution stack as follows:
6. The client's ``_update_auth()`` hook detects the header and transparently updates
the ``BearerAuth`` instance to use the new ``execution`` token for all subsequent requests.
+.. mermaid::
+
+ 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
Review Comment:
Diagram says `POST /run`, but the endpoint is `PATCH /{task_instance_id}/run`:
- Route: `@ti_id_router.patch("/{task_instance_id}/run", ...)` in `airflow-core/src/airflow/api_fastapi/execution_api/routes/task_instances.py`
- Client: `self.client.patch(f"task-instances/{id}/run", ...)` in `task-sdk/src/airflow/sdk/api/client.py`
Should be `PATCH` here to match.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #67435:
URL: https://github.com/apache/airflow/pull/67435#discussion_r3296482752
##########
airflow-core/docs/security/jwt_token_authentication.rst:
##########
@@ -242,6 +308,37 @@ The token flows through the execution stack as follows:
6. The client's ``_update_auth()`` hook detects the header and transparently updates
the ``BearerAuth`` instance to use the new ``execution`` token for all subsequent requests.
+.. mermaid::
+
+ 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
Review Comment:
Good catch — fixed. Endpoint is `PATCH /{task_instance_id}/run`; updated the diagram to `PATCH /run` to match.
---
Drafted-by: Claude Code (Opus 4.7); reviewed by @potiuk before posting
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Docs: refresh JWT and security model for v3.2 with mermaid diagrams [airflow]
Posted by "vatsrahul1001 (via GitHub)" <gi...@apache.org>.
vatsrahul1001 merged PR #67435:
URL: https://github.com/apache/airflow/pull/67435
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org