Skip to content

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

Draft
kirkbrauer wants to merge 10 commits into
mainfrom
jep/jep-0018-mtls-workload-identity
Draft

kirkbrauer wants to merge 10 commits into
mainfrom
jep/jep-0018-mtls-workload-identity

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.

Rendered proposal: https://github.com/jumpstarter-dev/jumpstarter/blob/29dad2001550a46f4ff9b12058a2a8b1cddc3ee9/docs/source/contributing/jeps/JEP-0018-mtls-workload-identity.md

(That link is pinned to a commit so it opens everywhere; the latest text is always under "Files changed".)

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).
  • Private keys are created in a key store: the OS keychain where there is one, otherwise a file. Hardware stores (TPM, Secure Enclave, PKCS#11) use the same interface and follow the Rust core.
  • Teleport and OpenZiti + SPIRE are worked through as reference integrations; SPIRE is the conformance target.
  • Bearer tokens keep working. Nothing changes on upgrade.

What a new user sees

The JEP holds itself to: no new commands, no new concepts, nothing extra to install, nothing to choose, and a working setup keeps working.

  • Local cluster (jmp admin create cluster): the same five commands as today. Enrollment runs against an operator-managed CA, so no approver-policy, OIDC provider or login endpoint is needed. Configs no longer contain a token, --insecure-tls drops out of the guide, and certificates renew in the background, with a grace period so an idle laptop or unplugged exporter recovers without a manual step.
  • Direct mode: today the documented path is --tls-grpc-insecure, optionally with a passphrase sent on every call. The JEP adds pairing: the exporter prints a one-time code, the laptop runs one command with it once, and every later jmp shell --tls-grpc HOST:PORT is mutual TLS with no other flag. Existing flags keep working.
  • Keys: on a laptop the key lands in the OS keychain without the user doing anything, so a lost or copied disk does not give access.

Known blockers and open design

The "Interface coverage" section walks every connection and lists what does not work yet.

  • In the controller today. Register and telemetry token issuance (GetServiceEndpoints) both read the bearer token directly, so a certificate-only exporter cannot register or discover endpoints. Small fixes, but nothing works without them.

  • Exporter-to-exporter (JEP-0015, JEP-0015: Multi-Exporter Leases and Inter-Exporter Port Forwarding #1069). JEP-0015 delivers its forwards over the router and leaves the authentication of its direct exporter-to-exporter path to this JEP, so an exporter has one identity, issued one way. That path is not designed here yet. What it will need:

    • A way for a Python exporter to verify the peer it dialed. Tested here: Python gRPC always checks a host name and cannot verify by SPIFFE ID alone, so a serving exporter's certificate would need a DNS name that stands for its identity. That would change this JEP's CSR rule, policy example and integration contract.
    • Identity trust bundles on exporters, which only the controller and routers hold today.
    • Serving usage on exporter certificates, and a loadable key for a Python listener (so no TPM for an exporter that serves peers until the Rust core does the serving).
    • One bound router token per side from JEP-0015's DialPeer.

    Whether to design this before acceptance or in a follow-up is Unresolved Question 7.

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 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 (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
Key storage Tokens and OIDC refresh tokens sit in the config file in plain text A key store interface. File and OS keychain stores ship in Python and protect keys at rest. Hardware stores need native signing APIs and, on macOS, a signed binary, so they follow the Rust core (DD-11)
Local clusters jmp admin create cluster already installs cert-manager and a self-signed serving CA, and created configs already carry that CA A second managed CA for identities; approver-policy only when the administrator supplies the issuer (DD-9)
Direct mode No client option to trust a private CA, so the only practical choices are no TLS or a passphrase. A Python gRPC server either requires a client certificate or ignores it Pairing with pinned certificates, bootstrapped by a temporary CA derived from the one-time code (DD-10)
Lease ceiling leasePolicy exists with maxTags, checked in CreateLease maxDuration is plumbed and checked the same way
Configuration The operator renders the config from the Jumpstarter CR; controller and router parse it strictly Operator CRD fields added; downgrade note added

Other 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.
  • Hardware key stores wait for the Rust core, which has no date (Unresolved Question 4).
  • Direct mode pairing shares the JEP's goal but none of its machinery; whether it belongs here or in its own JEP is Unresolved Question 8. Its code format needs a security review.
  • The lifetime and grace defaults for the managed issuer (30 days, 90 days) are proposals (Unresolved Question 2).
  • 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 says what was confirmed against the vendor documentation and what still has to be verified.

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
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
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
Remove statements left over from earlier revisions that contradicted
the current design: approver-policy described as always required, the
login service named as the EST host, an invalid certificate blocking a
permitted bearer token, and hardware-backed keys promised for the
Python client. Complete the API table, implementation map and test
plan for features the body already described.

Record which reference integration details were confirmed against the
Teleport, OpenZiti and SPIRE documentation and which remain open, and
specify how direct mode pairing works within the two client
certificate modes Python gRPC offers.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
Private keys are created in a key store and used through gRPC's
signing callback, so they can stay in a TPM, the Secure Enclave or an
OS keychain instead of a file. The default picks the best store the
machine offers without asking the user. Refresh tokens move to the
same stores.

This replaces the earlier assumption that the Python client could
only use keys it can read as bytes: grpcio 1.80 added a custom signer,
verified here against 1.83 on blocking and aio channels.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
The key store interface, the file store and the OS keychain stores
ship with the Python client and protect keys at rest. TPM, Secure
Enclave and PKCS#11 stores need native signing APIs and, on macOS, a
signed binary, so they follow the Rust core and are not a condition
for Beta or Stable.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
Walk every connection Jumpstarter makes and record where the proposal
does not yet work. Two are in the controller today: Register and
telemetry token issuance both read the bearer token directly, so a
certificate-only exporter cannot register or discover endpoints.

The rest are shared with JEP-0015, which defines its own exporter
certificates for the direct peer path: two issuers and ID formats for
one identity, a Python gRPC dialer that cannot verify a server by
SPIFFE ID alone, no identity trust bundle on exporters, serving usage
and loadable keys for peer listeners, and per-side router tokens.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
JEP-0015 no longer specifies exporter certificates and leaves the
authentication of direct exporter-to-exporter forwards to this JEP.
Replace the list of conflicts with the questions this JEP has to
answer before that path can be enabled: verifying a peer from Python,
trust anchors on exporters, serving usage, and bound router tokens
for forwards.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018WEcV44SFfjz4wMaY86WJ4
@mangelajo mangelajo added this to the 0.11.0 milestone Nov 16, 2026

This branch has not been deployed

No deployments
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.

3 participants