Merge pull request #34947 from bergerhoffer/pr-34077

Custom certs for the oAuth server route

Author: bergerhoffer

authentication/configuring-internal-oauth.adoc

@@ -15,6 +15,8 @@ include::modules/oauth-configuring-internal-oauth.adoc[leveloffset=+1]
 
 include::modules/oauth-configuring-token-inactivity-timeout.adoc[leveloffset=+1]
 
+include::modules/oauth-customizing-the-oauth-server-URL.adoc[leveloffset=+1]
+
 include::modules/oauth-server-metadata.adoc[leveloffset=+1]
 
 include::modules/oauth-troubleshooting-api-events.adoc[leveloffset=+1]

modules/customizing-the-web-console-URL.adoc

@@ -10,12 +10,12 @@ For `console` and `downloads` routes, custom routes functionality uses the `ingr
 [id="customizing-the-console-route_{context}"]
 == Customizing the console route
 
-You can customize the console route by setting the custom host name and TLS certificate in the `spec.componentRoutes` field of the cluster `Ingress` configuration.
+You can customize the console route by setting the custom hostname and TLS certificate in the `spec.componentRoutes` field of the cluster `Ingress` configuration.
 
 .Prerequisites
 
 * You have logged in to the cluster as a user with administrative privileges.
-* You have created a secret in the `openshift-config` namespace containing the TLS certificate and key. This is required if the domain for the custom host name suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
+* You have created a secret in the `openshift-config` namespace containing the TLS certificate and key. This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
 +
 [TIP]
 ====
@@ -31,7 +31,7 @@ You can create a TLS secret by using the `oc create secret tls` command.
 $ oc edit ingress.config.openshift.io cluster
 ----
 
-. Set the custom host name and optionally the serving certificate and key:
+. Set the custom hostname and optionally the serving certificate and key:
 +
 [source,yaml]
 ----
@@ -47,20 +47,20 @@ spec:
       servingCertKeyPairSecret:
         name: <secret_name> <2>
 ----
-<1> The custom host name.
-<2> Reference to a secret in the `openshift-config` namespace that contains a TLS certificate (`tls.crt`) and key (`tls.key`). This is required if the domain for the custom host name suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
+<1> The custom hostname.
+<2> Reference to a secret in the `openshift-config` namespace that contains a TLS certificate (`tls.crt`) and key (`tls.key`). This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
 
 . Save the file to apply the changes.
 
 [id="customizing-the-download-route_{context}"]
 == Customizing the download route
 
-You can customize the download route by setting the custom host name and TLS certificate in the `spec.componentRoutes` field of the cluster `Ingress` configuration.
+You can customize the download route by setting the custom hostname and TLS certificate in the `spec.componentRoutes` field of the cluster `Ingress` configuration.
 
 .Prerequisites
 
 * You have logged in to the cluster as a user with administrative privileges.
-* You have created a secret in the `openshift-config` namespace containing the TLS certificate and key. This is required if the domain for the custom host name suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
+* You have created a secret in the `openshift-config` namespace containing the TLS certificate and key. This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
 +
 [TIP]
 ====
@@ -76,7 +76,7 @@ You can create a TLS secret by using the `oc create secret tls` command.
 $ oc edit ingress.config.openshift.io cluster
 ----
 
-. Set the custom host name and optionally the serving certificate and key:
+. Set the custom hostname and optionally the serving certificate and key:
 +
 [source,yaml]
 ----
@@ -92,7 +92,7 @@ spec:
       servingCertKeyPairSecret:
         name: <secret_name> <2>
 ----
-<1> The custom host name.
-<2> Reference to a secret in the `openshift-config` namespace that contains a TLS certificate (`tls.crt`) and key (`tls.key`). This is required if the domain for the custom host name suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
+<1> The custom hostname.
+<2> Reference to a secret in the `openshift-config` namespace that contains a TLS certificate (`tls.crt`) and key (`tls.key`). This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
 
 . Save the file to apply the changes.

modules/oauth-customizing-the-oauth-server-URL.adoc

@@ -0,0 +1,60 @@
+// Module included in the following assemblies:
+//
+// * authentication/configuring-internal-oauth.adoc
+
+[id="customizing-the-oauth-server-url_{context}"]
+= Customizing the internal OAuth server URL
+
+You can customize the internal OAuth server URL by setting the custom hostname and TLS certificate in the `spec.componentRoutes` field of the cluster `Ingress` configuration.
+
+[WARNING]
+====
+If you update the internal OAuth server URL, you might break trust from components in the cluster that need to communicate with the OpenShift OAuth server to retrieve OAuth access tokens. Components that need to trust the OAuth server will need to include the proper CA bundle when calling OAuth endpoints. For example:
+
+[source,terminal]
+----
+$ oc login -u <username> -p <password> --certificate-authority=<path_to_ca.crt>
+----
+
+The Cluster Authentication Operator publishes the OAuth server's serving certificate in the `oauth-serving-cert` config map in the `openshift-config-managed` namespace. You can find the certificate in the `data.ca-bundle.crt` key of the config map.
+====
+
+.Prerequisites
+
+* You have logged in to the cluster as a user with administrative privileges.
+* You have created a secret in the `openshift-config` namespace containing the TLS certificate and key. This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
++
+[TIP]
+====
+You can create a TLS secret by using the `oc create secret tls` command.
+====
+
+.Procedure
+
+. Edit the cluster `Ingress` configuration:
++
+[source,terminal]
+----
+$ oc edit ingress.config.openshift.io cluster
+----
+
+. Set the custom hostname and optionally the serving certificate and key:
++
+[source,yaml]
+----
+apiVersion: config.openshift.io/v1
+kind: Ingress
+metadata:
+  name: cluster
+spec:
+  componentRoutes:
+    - name: oauth-openshift
+      namespace: openshift-authentication
+      hostname: <custom_hostname> <1>
+      servingCertKeyPairSecret:
+        name: <secret_name> <2>
+----
+<1> The custom hostname.
+<2> Reference to a secret in the `openshift-config` namespace that contains a TLS certificate (`tls.crt`) and key (`tls.key`). This is required if the domain for the custom hostname suffix does not match the cluster domain suffix. The secret is optional if the suffix matches.
+
+. Save the file to apply the changes.