OCPBUGS#30087: Hosted control planes: OAuth configuration

_topic_maps/_topic_map.yml

@@ -2311,6 +2311,8 @@ Topics:
   File: index
 - Name: Getting started with hosted control planes
   File: hcp-getting-started
+- Name: Authentication and authorization for hosted control planes
+  File: hcp-authentication-authorization
 - Name: Managing hosted control planes
   File: hcp-managing
 - Name: Using feature gates in a hosted cluster

hosted_control_planes/hcp-authentication-authorization.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="hcp-authentication-authorization"]
+= Authentication and authorization for hosted control planes
+include::_attributes/common-attributes.adoc[]
+:context: hcp-authentication-authorization
+
+toc::[]
+
+The {product-title} control plane includes a built-in OAuth server. You can obtain OAuth access tokens to authenticate to the {product-title} API. After you create your hosted cluster, you can configure OAuth by specifying an identity provider.
+
+include::modules/hcp-configuring-oauth.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+* To know more about supported identity providers, see xref:../authentication/understanding-identity-provider.adoc#understanding-identity-provider["Understanding identity provider configuration"] in _Authentication and authorization_.

modules/hcp-configuring-oauth.adoc

@@ -0,0 +1,64 @@
+// Module included in the following assemblies:
+//
+// * hosted_control_planes/hcp-authentication-authorization.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="hcp-configuring-oauth_{context}"]
+= Configuring the internal OAuth server for a hosted cluster
+
+You can configure the internal OAuth server for your hosted cluster by using an OpenID Connect identity provider. Adding any identity provider in the OAuth configuration removes the default `kubeadmin` user provider.
+
+.Prerequisites
+
+* You created your hosted cluster.
+
+.Procedure
+
+. Edit the `HostedCluster` custom resource (CR) on the hosting cluster by running the following command:
++
+[source,terminal]
+----
+$ oc edit <hosted_cluster_name> -n <hosted_cluster_namespace>
+----
+
+. Add the OAuth configuration in the `HostedCluster` CR by using the following example:
++
+[source,yaml]
+----
+apiVersion: hypershift.openshift.io/v1alpha1
+kind: HostedCluster
+metadata:
+  name: <hosted_cluster_name> <1>
+  namespace: <hosted_cluster_namespace> <2>
+spec:
+  configuration:
+    oauth:
+      identityProviders:
+      - openID: <3>
+          claims:
+            email: <4>
+              - <email_address>
+            name: <5>
+              - <display_name>
+            preferredUsername:
+              - <preferred_username> <6>
+          clientID: <client_id> <7>
+          clientSecret:
+            name: <client_id_secret_name> <8>
+          issuer: https://example.com/identity <9>
+        mappingMethod: lookup <10>
+        name: IAM
+        type: OpenID
+----
+<1> Specifies your hosted cluster name.
+<2> Specifies your hosted cluster namespace.
+<3> This provider name is prefixed to the value of the identity claim to form an identity name. The provider name is also used to build the redirect URL.
+<4> Defines a list of attributes to use as the email address.
+<5> Defines a list of attributes to use as a display name.
+<6> Defines a list of attributes to use as a preferred user name.
+<7> Defines the ID of a client registered with the OpenID provider. You must allow the client to redirect to the `\https://oauth-openshift.apps.<cluster_name>.<cluster_domain>/oauth2callback/<idp_provider_name>` URL.
+<8> Defines a secret of a client registered with the OpenID provider.
+<9> The link:https://openid.net/specs/openid-connect-core-1_0.html#IssuerIdentifier[Issuer Identifier] described in the OpenID spec. You must use `https` without query or fragment component.
+<10> Defines a mapping method that controls how mappings are established between identities of this provider and `User` objects.
+
+. Save the file to apply the changes.