procedures: native user auth docs

modules/administration-guide/nav.adoc

@@ -68,3 +68,4 @@
 ** xref:configuring-authorization.adoc[]
 ** xref:configuring-openshift-oauth.adoc[]
 ** xref:removing-user-data.adoc[]
+** xref:configuring-minikube-github-authentication.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,7 @@ include::partial$proc_listing-che-permissions.adoc[leveloffset=+1]
 
 include::partial$proc_assigning-che-permissions.adoc[leveloffset=+1]
 
+include::partial$con_devworkspace_auth.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

@@ -17,7 +17,10 @@ Creates and controls the necessary {orch-name} objects to run a {prod-short} ins
 `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.
 
+The {prod-short} operator is also provides routing for {devworkspace} by configuring the `che-gateway`.
+
 .Additional resources
 
 * xref:installation-guide:configuring-the-che-installation.adoc[]
 * xref:installation-guide:installing-che.adoc[]
+* xref:administration-guide:gateway.adoc[]

modules/administration-guide/partials/con_gateway.adoc

@@ -1,7 +1,12 @@
 [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 consists of 3 main parts:
+
+* *link:https://github.com/traefik/traefik[Traefik]* instance responsible for requests routing
+* *link:https://github.com/oauth2-proxy/oauth2-proxy[OAuth2-proxy]* ensuring authentication and initiating OAuth flow
+* *link:https://github.com/brancz/kube-rbac-proxy[kube-rbac-proxy]* applying {orch-name} Role based access control (RBAC) policies to control access to any {prod-short} resource.
+
 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,59 @@
+[id="configuring-minikube-github-authentication_{context}"]
+= Configuring Minikube with GitHub Authentication
+
+== Authentication on Kubernetes
+On {kubernetes}, link:https://github.com/oauth2-proxy/oauth2-proxy[OAuth2 Proxy] is deployed as che-gateway sidecar ensuring requests authentication. Then {kubernetes} must have configured OIDC issuer to know about users identities and CheCluster CR must be configured with:
+```
+spec:
+  auth:
+    identityProviderURL: <oidc-issuer-url>
+    oAuthClientName: <oauth-client-id>
+    oAuthSecret: <oauth-client-secret>
+```
+
+Chectl can configure minikube with link:https://dexidp.io/[Dex] as OIDC issuer with preconfigured static users. This is the default setup when deploying on Minikube with {devworkspace} engine `chectl server:deploy --platform minikube --workspace-engine=dev-workspace`. Dex can serve as a bridge to 3rd party {identity-provider}, like GitHub.
+
+=== Setup GitHub as identity provider on Kubernetes
+To setup GitHub as {prod-short} identity provider
+
+. Create OAuth App in GitHub at https://github.com/settings/applications/new (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.
++
+Note: To get minikube IP, run `$ minikube ip` in the terminal.
+
+
+. On GitHub Generate new client secret for just created OAuth application
+
+. edit dex configmap `kubectl edit configmap dex -n dex`
+```
+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.
++
+See link:https://dexidp.io/docs/connectors/github/[Dex documentation] for details
+
+Note: To remove dex static users, delete all `enablePasswordDB` and `staticPasswords` sections.
+
+. restart Dex pod to load new configuration `kubectl delete pod dex -n dex`
+
+. On next opening {prod-short} URL, user will be prompted with GitHub login