@@ -520,7 +520,7 @@ not yet use this client. Provisioning a token file alone does not switch that co
520520HTTP or remove its need for database access.
521521
522522In-memory sessions from workload identity
523- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
523+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
524524
525525Processor integrations can use ``WorkloadIdentitySessionTokenProvider `` to obtain and renew
526526``dag_processor_session `` credentials through ``POST /execution/dag-processor/session-token ``.
@@ -545,14 +545,20 @@ Use your identity provider's exact issuer, HTTPS JWKS URL, and signing algorithm
545545``ES256 ``, or ``EdDSA ``). Use a dedicated audience, distinct from ``[execution_api] jwt_audience ``.
546546The API server verifies the signature, issuer, audience, issued-at time, expiry, and any not-before
547547claim, using ``[api_auth] jwt_leeway `` for clock skew. Only exact subjects listed in ``grants `` can
548- obtain a session. Every granted bundle must be configured on the API server, which otherwise refuses
549- to start. This option is empty by default, disabling the exchange.
548+ obtain a session. If a grant names a Dag bundle that the API server does not have configured, the
549+ API server logs an error at startup and refuses that subject's exchanges with HTTP 403. This option
550+ is empty by default, disabling the exchange.
550551Apply the same trust configuration to all API-server replicas and restart them after changes.
551552
553+ The option trusts a single issuer. Dag processors whose identities come from different issuers, such
554+ as separate Kubernetes clusters, cannot all obtain sessions from the same API server.
555+
552556The JWKS endpoint must accept unauthenticated HTTPS GET requests from the Airflow API server.
553- The fetcher sends no authentication credentials and uses HTTPX's default certificate trust,
554- including ``SSL_CERT_FILE `` or ``SSL_CERT_DIR `` when configured. These environment settings affect
555- other HTTPX clients in the API-server process; there is no per-issuer CA or authentication option.
557+ The fetcher sends no authentication credentials and uses HTTPX's default certificate trust.
558+ ``SSL_CERT_FILE `` or ``SSL_CERT_DIR ``, when set, replace the default CA bundle rather than adding
559+ to it, and they apply to every HTTPX client in the API-server process. A bundle that holds only a
560+ private CA cuts those clients off from public roots, so include the roots they still need. There is
561+ no per-issuer CA or authentication option.
556562Authenticated JWKS endpoints, including Kubernetes API-server discovery protected by service-account
557563authentication, are not supported by this implementation. For those clusters, serve the public JWKS
558564through a suitable HTTPS endpoint before enabling the exchange. See Kubernetes'
@@ -586,7 +592,8 @@ The client does not wait automatically. This prevents two processes sharing an i
586592active Jobs at the same time.
587593
588594The processor integration supplies a callable that reads the current platform identity on each
589- exchange. For example:
595+ exchange. Any exception the callable raises is re-raised as ``WorkloadIdentityUnavailableError ``, an
596+ ``OSError ``, so a failed optional renewal leaves the valid Job credential in use. For example:
590597
591598.. code-block :: python
592599
@@ -613,8 +620,9 @@ session JWT to disk and does not fall back to a session-token file. ``token_prov
613620``token_file `` are mutually exclusive. HTTPS is required for the exchange, and redirects are rejected.
614621The exchange uses the same API TLS configuration and request timeout as the Task SDK client,
615622including private certificate authorities and client certificates. Registration retries transient
616- exchange failures using the configured Execution API retry policy; optional early renewal makes
617- one bounded attempt so it does not delay requests using a valid Job credential.
623+ exchange failures using the configured Execution API retry policy, waiting at least the
624+ ``Retry-After `` interval of an HTTP 503 before the next attempt. Optional early renewal makes one
625+ bounded attempt so it does not delay requests using a valid Job credential.
618626
619627Session expiry is capped by both the external identity's remaining lifetime and
620628``[execution_api] jwt_expiration_time ``. Clock-skew leeway never extends this cap, and an identity
@@ -631,12 +639,12 @@ unknown signing key. Fetches, including failed attempts, are limited to one per
631639API-server process. Publish new keys before signing with them and retain old keys while their tokens
632640remain valid.
633641
634- If a required signing key cannot be fetched, the exchange returns HTTP 503 with ``Retry-After ``,
635- allowing registration to retry . A cached matching key remains usable during an outage. Invalid
636- identities and keys absent from a successfully fetched keyset return HTTP 401.
642+ If a required signing key cannot be fetched, the exchange returns HTTP 503 with ``Retry-After ``, and
643+ registration waits at least that long before retrying . A cached matching key remains usable during
644+ an outage. Invalid identities and keys absent from a successfully fetched key set return HTTP 401.
637645
638646File-based provisioning
639- ~~~~~~~~~~~~~~~~~~~~~~~
647+ ^^^^^^^^^^^^^^^^^^^^^^^
640648
641649On a trusted host with the API signing key, provision a session token for the bundles
642650the client may access::
@@ -652,7 +660,7 @@ provisioner with the same token file and bundles keeps that session, so running
652660their Jobs.
653661
654662Credential permissions and renewal
655- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
663+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
656664
657665The three credentials have different issuers and permissions:
658666
0 commit comments