Provision GitHub OAuth using secret (eclipse-che#1773)

* Update github-auth doc

Signed-off-by: Anatolii Bazko <abazko@redhat.com>

Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>
Co-authored-by: Mario Loriedo <mario.loriedo@gmail.com>

modules/administration-guide/partials/assembly_configuring-authorization.adoc

@@ -17,6 +17,8 @@ include::example$proc_{project-context}-setting-up-user-federation.adoc[leveloff
 
 include::partial$proc_enabling-authentication-with-social-accounts-and-brokering.adoc[leveloffset=+1]
 
+include::partial$proc_configuring-github-oauth.adoc[leveloffset=+2]
+
 include::partial$proc_using-protocol-based-providers.adoc[leveloffset=+1]
 
 include::example$proc_{project-context}-managing-users-using-identity-provider.adoc[leveloffset=+1]

modules/administration-guide/partials/proc_configuring-github-oauth.adoc

@@ -0,0 +1,74 @@
+// Module included in the following assemblies:
+//
+// Configuring GitHub OAuth
+
+
+[id="configuring-github-oauth_{context}"]
+= Configuring GitHub OAuth
+
+OAuth for GitHub allows for automatic SSH key upload to GitHub.
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+
+.Procedure
+
+* Create a link:https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app[OAuth application in GitHub] using {prod-short} URL as the value for the application `Homepage URL` and {identity-provider} GitHub endpoint URL as the value for Authorization callback URL. The default values are `https://{prod-deployment}-{prod-namespace}.<DOMAIN>/` and `https://keycloak-{prod-namespace}.<DOMAIN>/auth/realms/{prod-deployment}/broker/github/endpoint` respectively, where `<DOMAIN>` is {orch-name} cluster domain.
+
+ifeval::["{project-context}" == "che"]
+* For {prod-short} deployed in multi-user mode:
++
+endif::[]
+
+. Create a new secret in the {orch-namespace} where {prod-short} is deployed.
++
+[subs="+quotes,+attributes"]
+----
+$ {orch-cli} apply -f - <<EOF
+kind: Secret
+apiVersion: v1
+metadata:
+  name: github-oauth-credentials
+  namespace: <...> <1>
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: keycloak-secret
+  annotations:
+    che.eclipse.org/github-oauth-credentials: 'true'
+    che.eclipse.org/mount-as: env
+    che.eclipse.org/id_env-name: GITHUB_CLIENT_ID
+    che.eclipse.org/secret_env-name: GITHUB_SECRET
+data:
+  id: <...> <2>
+  secret: <...> <3>
+type: Opaque
+EOF
+----
+<1> {prod-short} namespace. The default is {prod-namespace}
+<2> base64 encoded GitHub OAuth Client ID
+<3> base64 encoded GitHub OAuth Client Secret
+
+. If {prod-short} was already installed wait until rollout of {identity-provider} component finishes.
+
+ifeval::["{project-context}" == "che"]
++
+
+* For {prod-short} deployed in single-user mode:
+. On {platforms-name}, update the deployment configuration (see xref:installation-guide:configuring-the-che-installation.adoc[] and xref:installation-guide:advanced-configuration-options-for-the-che-server-component.adoc#authentication-parameters[]).
++
+[subs=+quotes]
+----
+CHE_OAUTH_GITHUB_CLIENTID=__<your-github-client-ID>__
+CHE_OAUTH_GITHUB_CLIENTSECRET=__<your-github-secret>__
+----
+
+. In the *Authorization callback URL* field of the GitHub OAuth application, enter `__<prod-url__/api/oauth/callback`.
++
+[NOTE]
+====
+* Substitute `_<prod-url>_` with the URL and port of the {prod-short} installation.
+* Substitute `_<your-github-client-ID>_` and `_<your-github-secret>_` with your GitHub client ID and secret.
+* This configuration only applies to single-user deployments of {prod-short}.
+====
+endif::[]

modules/administration-guide/partials/proc_enabling-authentication-with-social-accounts-and-brokering.adoc

@@ -3,24 +3,9 @@
 [id="enabling-authentication-with-social-accounts-and-brokering_{context}"]
 = Enabling authentication with social accounts and brokering
 
-{identity-provider} provides built-in support for GitHub, OpenShift, and most common social networks such as Facebook and Twitter. 
+{identity-provider} provides built-in support for GitHub, OpenShift, and most common social networks such as Facebook and Twitter.
 See {identity-provider} documentation to learn how to link:{link-identity-provider-github}[enable Login with GitHub].
 
-You can also enable the SSH key and upload it to the {prod-short} users’ GitHub accounts.
-
-To enable this feature when you register a GitHub identity provider:
-
-. Set scope to `repo,user,write:public_key`.
-
-. Set store tokens and stored tokens readable to *ON*.
-+
-image::git/kc_provider.png[link="../_images/git/kc_provider.png"]
-
-. Add a default read-token role.
-+
-image::git/kc_roles.png[link="../_images/git/kc_roles.png"]
-
-This is the default `delegated` OAuth service mode for multiuser {prod-short}. You can configure the OAuth service mode with the property `che.oauth.service_mode`.
 
 // TODO: To use {prod-short}'s OAuth Authenticator, set `che.oauth.service_mode` to `embedded` and use xref:end-user-guide:version-control.adoc[].
 

modules/end-user-guide/nav.adoc

@@ -33,7 +33,6 @@
 ** xref:adding-tools-to-che-after-creating-a-workspace.adoc[]
 ** xref:editing-a-devfile-and-plug-in-at-runtime.adoc[]
 * xref:configuring-oauth-authorization.adoc[]
-** xref:configuring-github-oauth.adoc[]
 ** xref:configuring-openshift-oauth.adoc[]
 * xref:using-artifact-repositories-in-a-restricted-environment.adoc[]
 ** xref:using-maven-artifact-repositories.adoc[]

modules/end-user-guide/partials/assembly_configuring-oauth-authorization.adoc

@@ -9,8 +9,6 @@
 
 This section describes how to connect {prod} as an OAuth application to supported OAuth providers.
 
-* xref:configuring-github-oauth.adoc[]
-
 * xref:configuring-openshift-oauth.adoc[]
 
 :context: {parent-context-of-configuring-oauth-authorization}

modules/end-user-guide/partials/proc_managing-pull-requests-using-the-github-pr-plug-in.adoc

@@ -12,7 +12,7 @@ To manage GitHub pull requests, the VS Code GitHub Pull Request plug-in is avail
 
 .Prerequisites
 
-* GitHub OAuth is configured. See xref:configuring-github-oauth.adoc[].
+* GitHub OAuth is configured. See xref:administration-guide:configuring-authorization#configuring-github-oauth_configuring-authorization[Configuring GitHub OAuth].
 
 .Procedure