From ab0641d1e978e9265ecb1daccf5df9cb18ac6fe3 Mon Sep 17 00:00:00 2001 From: Joshua Casey Date: Tue, 13 Jun 2023 16:48:08 -0500 Subject: [PATCH] Add proposal to implement #1547, Concierge Impersonation Proxy | External Certificate Management --- .../README.md | 167 ++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 proposals/1547_impersonation-proxy-external-certs/README.md diff --git a/proposals/1547_impersonation-proxy-external-certs/README.md b/proposals/1547_impersonation-proxy-external-certs/README.md new file mode 100644 index 000000000..9e48417f6 --- /dev/null +++ b/proposals/1547_impersonation-proxy-external-certs/README.md @@ -0,0 +1,167 @@ +--- +title: "Concierge Impersonation Proxy | External Certificate Management" +authors: [ "@joshuatcasey" ] +status: "in-review" +sponsor: [ "@cfryanr", "@benjaminapetersen" ] +approval_date: "" +--- + +*Disclaimer*: Proposals are point-in-time designs and decisions. +Once approved and implemented, they become historical documents. +If you are reading an old proposal, please be aware that the +features described herein might have continued to evolve since. + +# Concierge Impersonation Proxy | External Certificate Management + +## Problem Statement + +The impersonation proxy cannot be configured with an external certificate, meaning its CA bundle must be downloaded +and baked into the Kubeconfig. We should allow Pinniped admins to specify an externally-provided certificate so that +the impersonation proxy could serve TLS using out of band PKI for TLS verification. + +This has the impact of easing integration with ingress providers so that we can put ingress in front of the +impersonation proxy. +Note that the impersonation proxy does use mTLS to verify the user's identity, so the ingress should support TLS +passthrough or something similar. + +### How Pinniped Works Today (as of version v0.24.0) + +The impersonation proxy today generates a CA and a serving certificate to serve TLS. +This will be referred to as the “generated cert” below. + +## Terminology / Concepts + +* Generated cert: The certificate that the impersonation proxy will generate +* External cert: A certificate provied by something outside of Pinniped, meant for the impersonation proxy to serve TLS + +## Proposal + +Allow Pinniped admins to specify an externally-provided certificate and CA bundle for the impersonation proxy to use +to serve TLS. + +### Goals and Non-goals + +This proposal does not provide implementation details for the following deferred cases: + +* Detecting the ca.crt from the TLS secret +* SAN/IP address validation from the CA or serving cert +* Using forwarded client certificate details (such as `x-forwarded-client-cert` from https://projectcontour.io/docs/1.25/config/tls-termination/#client-certificate-details-forwarding) for authentication instead of mTLS. + +#### API Changes + +```yaml +apiVersion: "config.concierge.pinniped.dev/v1alpha1" +kind: CredentialIssuer +metadata: + name: the-credential-issuer +spec: + impersonationProxy: + mode: auto + externalEndpoint: impersonation-proxy.example.com + service: + loadBalancerIP: 1.2.3.4 + # Proposed API below: + tls: + # certificateAuthorityData contains a CA bundle. This value is not used by the impersation proxy to serve TLS. + # This value will be advertised to clients so that they can perform TLS verification with the impersonation proxy. + # Specifying multiple CA certs can assist with CA rotation. + # Optional. If not provided, no CA bundle will be advertised for clients. + certificateAuthorityData: + + # Names a secret of type "kubernetes.io/tls" (https://kubernetes.io/docs/concepts/configuration/secret/#tls-secrets) + # which must contain both a TLS serving certificate and the private key, and which is in the same namespace. + # Eventually, this will support using the "ca.crt" field which is sometimes provided by cert-manager + # (https://cert-manager.io/docs/concepts/certificate/), instead of providing certificateAuthorityData above. + # Eventually, this serving certificate may be validated against the above externalEndpoint and/or loadBalancerIP. + # Required if the tls parent is set. + secretName: my-tls-cert +``` + +#### Upgrades + +* Upgrading an existing impersonation proxy installation currently using a generated cert should continue to work as-is + without intervention +* Upgrading an existing impersonation proxy installation currently using a generated cert should allow easy transfer to + an external cert. + The impersonation proxy will clean up its own generated certs that are no longer used. + This will require manual intervention for at least the following: + * Configure the external cert secret (using cert-manager, manually generated certs, or any other mechanism) + * Configure the CredentialIssuer with the new tls configuration block + * Regenerate and distribute a new kubeconfig for that cluster +* Installing a new impersonation proxy with an external cert should work without ever generating a cert +* Switching an impersonation proxy from an external cert to a generated cert should work by performing the following + manual interventions: + * Remove the new tls configuration block from the CredentialIssuer + * Clean up existing external CA/cert secret objects, and prevent their regeneration + * Regenerate and distribute a new kubeconfig for that cluster + +#### Tests + +No new integration tests, since the verification likely requires multiple components not typically installed during +integration tests +such as cert-manager and contour. + +#### New Dependencies + +No. + +#### Performance Considerations + +No. + +#### Observability Considerations + +The impersonation proxy will log a message when it detects any of the following situations: + +* Generate a cert to serve TLS +* Use an external cert to serve TLS +* Cleanup of any unused resources +* Error conditions from the external cert + * secret not found + * tls.crt or tls.key not available in the secret + * etc + +#### Security Considerations + +None. TLS verification will always be enforced by the Pinniped CLI client. + +#### Usability Considerations + +We designed the API behavior such that it was backwards-compatible and works out of the box. + +#### Documentation Considerations + +This design doc serves as an announcement that the feature will be implemented. +It would be helpful to provide a blog post describing how the feature was validated. +Also include in release notes. + +### Other Approaches Considered + +None. + +## Open Questions + +A list of questions that need to be answered. + +## Answered Questions + +* Can the Impersonation Proxy use the K8s API server TLS cert and key? + * No. The impersonation proxy is typically only used when the API server signing key is unavailable. +* Can ingress (such as contour with TLS passthrough) provide support for mTLS? + * Unknown, will check during validation. + Other ingress providers may have support for this, although we will not provide a list of compatible providers. + It is out of scope for us to test beyond what is necessary to validate that the impersonation proxy is configured + correctly. + +## Implementation Plan + +Three different PRs can implement this in phases: + +1. Add the new API, and support the various upgrade/configuration scenarios +2. Add support for the CA bundle in the secret instead of certificateAuthorityData +3. Verify that the CA bundle or serving cert references the same DNS names or IP addresses known to the impersonation + proxy. + +## Implementation PRs + +* TBD