Add proposal to implement #1547, Concierge Impersonation Proxy | Exte…

…rnal Certificate Management

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: <ca-bundle>
+
+      # 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