Repository navigation
JEP-0018: mTLS Workload Identity as the Default Authentication Mechanism - #1337
Draft
kirkbrauer wants to merge 10 commits into
Draft
kirkbrauer wants to merge 10 commits into
kirkbrauer wants to merge 10 commits into
Conversation
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
Contributor
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
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. |
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
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
exec,spiffe,enrollment,file, and today'stoken).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.
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-tlsdrops 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.--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 laterjmp shell --tls-grpc HOST:PORTis mutual TLS with no other flag. Existing flags keep working.Known blockers and open design
The "Interface coverage" section walks every connection and lists what does not work yet.
In the controller today.
Registerand 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:
DialPeer.Whether to design this before acceptance or in a follow-up is Unresolved Question 7.
How it fits the code on
mainThe 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:
MetadataAttributesGetterderives the object name from any non-internal username, so a SPIFFE ID username would be forced onto a name likelab-example-com-jumpstarter-exporters-pi-07:8086behind edge TLS termination, so a client certificate cannot reach it:8082listener, which is passthrough and already sends non-gRPC requests to a gateway mux with no routes (DD-6)Dialmints one token and gives the same string to both sides. The exporter's only known certificate is the one on its long-livedListenstreamUNAVAILABLE, which it retries as an outageUNAUTHENTICATED(DD-4)clientAuth: Requiredbearer.allowedPrincipalscsrattrs; the controller rejects any other namessl_channel_credentials;cryptographyis already a dependencymain, not deferred to the Rust corejmp admin create clusteralready installs cert-manager and a self-signed serving CA, and created configs already carry that CAleasePolicyexists withmaxTags, checked inCreateLeasemaxDurationis plumbed and checked the same wayJumpstarterCR; controller and router parse it strictlyOther open points
identifiesrule they introduce. It should be implemented after them, and re-read if they change shape.Checks
make docsbuilds without warnings with the controller-version lookup stubbed locally; that lookup needsquay.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