Skip to content

JEP-0018: mTLS Workload Identity as the Default Authentication Mechanism - #1336

Closed
kirkbrauer wants to merge 4 commits into
mainfrom
claude/loving-clarke-zvcphc
Closed

kirkbrauer wants to merge 4 commits into
mainfrom
claude/loving-clarke-zvcphc

Conversation

@kirkbrauer

@kirkbrauer kirkbrauer commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Adds JEP-0018 and lists it in the JEP index. Status is Draft; this PR is the discussion venue.

What it proposes

Mutual TLS with SPIFFE X.509 identities as the default way clients and exporters authenticate, in place of bearer tokens:

  • The controller and routers verify client certificates against per-trust-domain bundles and map the SPIFFE ID to a Jumpstarter username, object name and groups with CEL.
  • Certificates come from any issuer that meets a small vendor-neutral contract, or from a built-in EST endpoint where the controller is a registration authority in front of cert-manager.
  • Clients and exporters get credentials through pluggable sources (exec, spiffe, enrollment, file, and today's token).
  • Teleport and OpenZiti + SPIRE are worked through as reference integrations; SPIRE is the conformance target.
  • Bearer tokens keep working. Nothing changes on upgrade.

How it fits the code on main

The JEP was checked against the controller, router, operator and Python client, and the design was adjusted wherever the code contradicted it. The "Implementation map" section of the JEP lists where each change lands. The points most worth a reviewer's attention:

Topic What the code does today What the JEP does
Object resolution MetadataAttributesGetter derives the object name from any non-internal username, so a SPIFFE ID username would be forced onto a name like lab-example-com-jumpstarter-exporters-pi-07 Builds on the credential-kind pattern of #1319 and #1320. Enrollment certificates carry the object's internal subject (UID included) as their path and are internal credentials, so the authorizer is untouched. Certificates from other domains add one branch that takes the name from the mapping (DD-7)
EST endpoint The login service is plain HTTP on :8086 behind edge TLS termination, so a client certificate cannot reach it EST is served on the controller's :8082 listener, which is passthrough and already sends non-gRPC requests to a gateway mux with no routes (DD-6)
Router tokens Dial mints one token and gives the same string to both sides. The exporter's only known certificate is the one on its long-lived Listen stream One token per side, bound to the SPIFFE ID rather than the certificate thumbprint, so rotation does not break it. The exporter's identity is read from its Listen queue entry (DD-8)
Certificate verification A handshake rejection reaches the Python client as UNAVAILABLE, which it retries as an outage TLS requests the certificate; the authenticator verifies it and returns UNAUTHENTICATED (DD-4)
clientAuth: Required First enrollment has no certificate and shares the listener Rejected at startup together with enrollment; strictness comes from bearer.allowedPrincipals
CSR contents A CSR is signed by the caller; cert-manager and approver-policy act on its contents The caller learns its SPIFFE ID from EST csrattrs; the controller rejects any other name
Client side TLS credentials for controller, exporter and router connections are all built in ssl_channel_credentials; cryptography is already a dependency Credential sources are implemented in the Python client on main, not deferred to the Rust core
Lease ceiling leasePolicy exists with maxTags, checked in CreateLease maxDuration is plumbed and checked the same way, in CreateLease and UpdateLease
Configuration The operator renders the config from the Jumpstarter CR; controller and router parse it strictly Operator CRD fields added; downgrade note added

Design Decisions (DD-1 to DD-9), Acceptance Criteria and Consequences were added, as the template requires for Standards Track.

Open points

  • Depends on fix(controller): recognise internal tokens by the issuer that verified them #1319 and fix(controller): bind each kind of token to its own identity #1320. The object-resolution design uses the marked user type and the split identifies rule they introduce. It should be implemented after them, and re-read if they change shape.
  • Two proposals the JEP refers to, driver access rules and ExporterClass onboarding, are not published in this repository; they are marked as such.
  • The Teleport, OpenZiti and SPIRE snippets are illustrative. Each section ends with a list of what still has to be verified against those products. The approver-policy requirements (default approver disabled, approveSignerNames for external issuers) were checked against the cert-manager documentation.
  • Dial reaches an exporter only through the controller replica holding its Listen stream. That is existing behavior, and token binding relies on it (Unresolved Question 7).

Checks

make docs builds without warnings with the controller-version lookup stubbed locally; that lookup needs quay.io, which was unreachable from the environment this was prepared in. The stub is not part of this PR.

🤖 Generated with Claude Code

https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4

Propose mutual TLS with SPIFFE X.509 identities as the default
authentication mechanism, with a vendor-neutral integration contract,
built-in EST enrollment in front of cert-manager, and Teleport and
OpenZiti + SPIRE reference integrations.

The draft was checked against the controller, router, operator and
Python client on main. Where the code contradicted it, the proposal
was corrected: EST is served on the controller's passthrough listener
rather than the edge-terminated login service, X.509 identities get
their own object resolution rule, router tokens are issued per side
and bound to the SPIFFE ID, and certificates are verified in the
authenticator rather than in the TLS handshake.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
@coderabbitai

coderabbitai Bot commented Nov 12, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@kirkbrauer kirkbrauer added the jep Jumpstarter Enhancement Proposals label Nov 12, 2026 — with Claude
Enrollment certificates now carry the object's internal subject as
their SPIFFE path and are treated as internal credentials, so they
reuse the credential-kind rules from #1319 and #1320 and leave the
authorizer unchanged. Certificates from other trust domains add one
branch to object resolution.

Credential sources target the Python client and exporter on main
instead of waiting for the Rust core. Router token binding, the lease
ceiling and the EST handlers are tied to the code they extend, and an
implementation map lists where each change lands.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
Local clusters made with 'jmp admin create cluster' enroll against an
operator-managed CA, so the getting-started commands stay the same and
need no approver-policy, OIDC provider or insecure flag. A renewal
grace period keeps an idle laptop or unplugged exporter working.

Direct mode gains pairing: a one-time code, then mutual TLS between
remembered certificates, replacing the insecure flag and the
passphrase as the documented path.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4

Copy link
Copy Markdown
Member Author

Closing in favour of #1337. The source branch was renamed to jep/jep-0018-mtls-workload-identity, and a pull request's source branch cannot be changed, so the JEP continues there with the same commits.


Generated by Claude Code

@kirkbrauer kirkbrauer closed this Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

jep Jumpstarter Enhancement Proposals

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants