diff --git a/deploy/supervisor/README.md b/deploy/supervisor/README.md index 5a751ee4..5ad6d51f 100644 --- a/deploy/supervisor/README.md +++ b/deploy/supervisor/README.md @@ -147,13 +147,37 @@ spec: # The hostname would typically match the DNS name of the public ingress or load balancer for the cluster. # Any path can be specified, which allows a single hostname to have multiple different issuers. The path is optional. issuer: https://my-issuer.example.com/any/path + # Optionally configure the name of a Secret in the same namespace, of type `kubernetes.io/tls`, + # which contains the TLS serving certificate for the HTTPS endpoints served by this OIDC Provider. + sniCertificateSecretName: my-tls-cert-secret ``` -If you are using a LoadBalancer Service to expose the Supervisor app outside your cluster, then you will -also need to configure the OIDCProviderConfig with TLS certificates, so the app can terminate TLS. -You can create the certificates however you like, for example you could use [cert-manager](https://cert-manager.io/). -Keep in mind that your users will load some of these endpoints in their web browsers, so the TLS certificates -should be signed by a Certificate Authority that will be trusted by those browsers. +#### Configuring TLS for the Supervisor OIDC Endpoints If you have terminated TLS outside the app, for example using an Ingress with TLS certificates, then you do not need to configure TLS certificates on the OIDCProviderConfig. + +If you are using a LoadBalancer Service to expose the Supervisor app outside your cluster, then you will +also need to configure the Supervisor app to terminate TLS. There are two places to configure TLS certificates: + +1. Each `OIDCProviderConfig` can be configured with TLS certificates, using the `sniCertificateSecretName` field. + +1. The default TLS certificate for all OIDC providers can be configured by creating a Secret called +`pinniped-supervisor-default-tls-certificate` in the same namespace in which the Supervisor was installed. + +The default TLS certificate will be used for all OIDC providers which did not declare an `sniCertificateSecretName`. +Also, the `sniCertificateSecretName` will be ignored for incoming requests to the OIDC endpoints +that use an IP address as the host, so those requests will always present the default TLS certificates +to the client. When the request includes the hostname, and that hostname matches the hostname of an `Issuer`, +then the TLS certificate defined by the `sniCertificateSecretName` will be used. If that issuer did not +define `sniCertificateSecretName` then the default TLS certificate will be used. If neither exists, +then the client will get a TLS error because the server will not present any TLS certificate. + +It is recommended that you have a DNS entry for your load balancer or Ingress, and that you configure the +OIDC provider's `Issuer` using that DNS hostname, and that the TLS certificate for that provider also +covers that same hostname. + +You can create the certificate Secrets however you like, for example you could use [cert-manager](https://cert-manager.io/) +or `kubectl create secret tls`. +Keep in mind that your users will load some of these endpoints in their web browsers, so the TLS certificates +should be signed by a Certificate Authority that will be trusted by their browsers.