procedures: native user auth docs

.vale/styles/CheDocs/Spelling.yml

@@ -129,6 +129,7 @@ filters:
   - Datadog
   - Dev
   - DevWorkspace
+  - Dex
   - DNS
   - Docker
   - Dockerfile

antora.yml

@@ -61,6 +61,9 @@ asciidoc:
     link-installing-an-instance: xref:installation-guide:installing-che.adoc[]
     link-server-identity-provider-dockerfile-location: https://github.com/eclipse-che/che-server/tree/main/dockerfiles/keycloak
     link-viewing-the-state-of-the-cluster-deployment-using-openshift-4-cli-tools: xref:overview:installing-che-on-openshift-4-using-operatorhub.adoc[]
+    link-oauth2-proxy: link:https://github.com/oauth2-proxy/oauth2-proxy[OAuth2 Proxy]
+    link-kube-rbac-proxy: link:https://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy]
+    link-oidc-issuer: link:https://dexidp.io/[Dex]
     namespace: namespace # In context: API namespace
     nodejs-stack: nodejs
     ocp: OpenShift Container Platform

modules/administration-guide/nav.adoc

@@ -68,5 +68,7 @@
 ** xref:authenticating-users.adoc[]
 ** xref:authorizing-users.adoc[]
 ** xref:configuring-authorization.adoc[]
-** xref:configuring-openshift-oauth.adoc[]
+*** xref:configuring-openshift-oauth.adoc[]
+*** xref:configuring-minikube-github-authentication.adoc[]
+
 ** xref:removing-user-data.adoc[]

modules/administration-guide/pages/configuring-minikube-github-authentication.adoc

@@ -0,0 +1,7 @@
+[id="configuring-openshift-oauth"]
+// = Configuring OpenShift OAuth
+:navtitle: Configuring Minikube GitHub Authentication
+:keywords: administration-guide, configuring-openshift-oauth
+:page-aliases: .:configuring-minikube-github-authentication
+
+include::partial$proc_configuring-minikube-github-authentication.adoc[]

modules/administration-guide/pages/configuring-openshift-oauth.adoc

@@ -1,7 +1,7 @@
 [id="configuring-openshift-oauth"]
 // = Configuring OpenShift OAuth
 :navtitle: Configuring OpenShift OAuth
-:keywords: end-user-guide, configuring-openshift-oauth
+:keywords: administration-guide, configuring-openshift-oauth
 :page-aliases: .:configuring-openshift-oauth
 
 include::partial$proc_configuring-openshift-oauth.adoc[]

modules/administration-guide/pages/managing-identities-and-authorizations.adoc

@@ -1,7 +1,7 @@
 [id="managing-identities-and-authorizations"]
 // = Managing identities and authorizations
 :navtitle: Managing identities and authorizations
-:keywords: end-user-guide, managing-identities-and-authorizations
+:keywords: administration-guide, managing-identities-and-authorizations
 :page-aliases: .:managing-identities-and-authorizations
 
 include::partial$assembly_managing-identities-and-authorizations.adoc[]

modules/administration-guide/partials/assembly_authorizing-users.adoc

@@ -33,5 +33,4 @@ include::partial$proc_listing-che-permissions.adoc[leveloffset=+1]
 
 include::partial$proc_assigning-che-permissions.adoc[leveloffset=+1]
 
-
 :context: {parent-context-of-authorizing-users}

modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc

@@ -13,5 +13,6 @@ This section describes different aspects of managing identities and authorizatio
 * xref:configuring-authorization.adoc[]
 * xref:removing-user-data.adoc[]
 * xref:configuring-openshift-oauth.adoc[]
+* xref:configuring-minikube-github-authentication.adoc[]
 
 :context: {parent-context-of-managing-identities-and-authorizations}

modules/administration-guide/partials/con_che-operator.adoc

@@ -15,7 +15,15 @@ Defines the `CheCluster` {orch-name} object.
 Creates and controls the necessary {orch-name} objects to run a {prod-short} instance, such as pods, services, and persistent volumes.
 
 `CheCluster` custom resource (CR)::
-On a cluster with the {prod-short} operator, it is possible to create a `CheCluster` custom resource (CR). The {prod-short} operator ensure full lifecycle management of the {prod-short} server components on this {prod-short} instance.
+On a cluster with the {prod-short} operator, it is possible to create a `CheCluster` custom resource (CR). The {prod-short} operator ensure full lifecycle management of the {prod-short} server components on this {prod-short} instance:
++
+* xref:devworkspace-operator.adoc[]
+* xref:gateway.adoc[]
+* xref:dashboard.adoc[]
+* xref:devfile-registries.adoc[]
+* xref:che-server.adoc[]
+* xref:postgresql.adoc[]
+* xref:plug-in-registry.adoc[]
 
 .Additional resources
 

modules/administration-guide/partials/con_gateway.adoc

@@ -1,7 +1,14 @@
 [id="gateway_{context}"]
 = Gateway
 
-The {prod-short} gateway is a Traefik instance applying {orch-name} Role based access control (RBAC) policies to control access to any {prod-short} resource.
+The {prod-short} gateway has following roles:
+
+* Routing requests. It uses link:https://github.com/traefik/traefik[Traefik].
+
+* Authenticating users with OpenID Connect (OIDC). It uses {link-oauth2-proxy}.
+
+* Applying {orch-name} Role based access control (RBAC) policies to control access to any {prod-short} resource. It uses {link-kube-rbac-proxy}. 
+
 The {prod-short} operator manages it as the `che-gateway` Deployment.
 
 It controls access to:

modules/administration-guide/partials/proc_configuring-minikube-github-authentication.adoc

@@ -0,0 +1,69 @@
+[id="configuring-minikube-github-authentication_{context}"]
+= Configuring Minikube with GitHub Authentication
+
+
+On Minikube, {prod-cli} provides a default OpenID Connect (OIDC) issuer, which can serve as a bridge to third party {identity-provider}, such as GitHub.
+{link-oidc-issuer} is the default OIDC issuer, preconfigured with static users.
+Configure {link-oidc-issuer} to use GitHub authentication.
+
+.Prerequisites
+
+* {prod-short} is installed on Minikube. See xref:installation-guide:installing-che-on-minikube.adoc[].
+
+
+.Procedure
+. Get Minikube IP and remember it as `_<minikube_ip>_`:
++
+----
+$ minikube ip
+----
+
+. link:https://github.com/settings/applications/new[Create an OAuth App] for your Minikube instance in GitHub. See link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub documentation].
++
+[source]
+----
+Application name: Eclipse Che <1>
+Homepage URL: https://<minikube_ip>.nip.io <2>
+Authorization callback URL: https://dex.<minikube_ip>.nip.io/callback <3>
+----
++
+<1> Name is only displayed on GitHub. It is not used internally so it can be any name.
+<2> Main URL to Che instance.
+<3> Callback URL to Dex. Chectl deploys Dex on `dex.` subdomain.
+
+
+. In the GitHub OAuth application page, click btn:[Generate a new client secret] and remember the value of the generated client secret as `_<client_secret>_`.
+
+. Edit the {link-oidc-issuer} config map:
++
+----
+$ kubectl edit configmap dex -n dex
+----
++
+[source,yaml,subs="+attributes,macros,quotes"]
+----
+connectors:
+- type: github
+  id: github
+  name: GitHub
+  config:
+    clientID: _<client_id>_ <1>
+    clientSecret: _<client_secret>_ <2>
+    redirectURI: https://dex._<minikube_ip>_.nip.io/callback <3>
+----
++
+<1> OAuth client id copied from GitHub OAuth application
+<2> OAuth client secret, generated at GitHub in previous step
+<3> Callback URL to Dex. This must match configuration in GitHub OAuth application from step 1.
+
+Note: To remove Dex static users, delete all `enablePasswordDB` and `staticPasswords` sections.
+
+. Restart the {link-oidc-issuer} pod:
++
+----
+$ kubectl delete pod dex -n dex
+----
+
+.Verification steps
+
+* Open {prod-short} URL. The dashboard displays GitHub login prompt.

modules/installation-guide/partials/proc_enabling-dev-workspace-operator.adoc

@@ -2,7 +2,7 @@
 [id="enabling-dev-workspace-operator_{context}"]
 = Enabling {devworkspace} operator
 
-This procedure describes how to enable the {devworkspace} operator to support the Devfile 2.0.0 file format and mentions how to do so on existing instances or those about to be installed.
+This procedure describes how to enable the {devworkspace} operator to support the Devfile v2 file format and mentions how to do so on existing instances or those about to be installed.
 
 .Prerequisites
 
@@ -32,18 +32,25 @@ spec:
 +
 [subs="+quotes,+attributes"]
 ----
-$ {prod-cli} server:deploy --che-operator-cr-patch-yaml=patch.yaml ...
+$ {prod-cli} server:deploy --workspace-engine=dev-workspace ...
 ----
-+
-`patch.yaml` must contain the following:
-+
+
+ifeval::["{project-context}" == "che"]
+[WARNING]
+====
+{prod-cli} will automatically setup Dex as OIDC provider on Minikube. For other {kubernetes} clusters setup link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server[{kubernetes} OIDC] provider following cluster provider documentation and set the following values in {prod-checluster} Custom Resource (CR):
+
 [source,yaml,subs="+quotes"]
 ----
 spec:
-  devWorkspace:
-    enable: true
+  auth:
+    identityProviderURL: '__<oidc_url>__' <1>
 ----
 
+<1> URL to OIDC provider.
+====
+endif::[]
+
 * For already existing {prod-short} installation:
 +
 . Update `{prod-checluster}` CR using the `{orch-cli}` tool: