Add Gitlab authentication procedure using personal tokens (#1924)

* Add Gitlab authentication procedure using personal tokens

* Missing files

* Fixups

* Rename doc

* review-part-1

Signed-off-by: Michal Maléř <mmaler@redhat.com>

* review

Signed-off-by: Michal Maléř <mmaler@redhat.com>

* Fixup filename and remove old

* Fixup file

* Add renamed file

* Fixup

* vale

Signed-off-by: Michal Maléř <mmaler@redhat.com>

Co-authored-by: Michal Maléř <mmaler@redhat.com>

modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc

@@ -57,11 +57,11 @@ The `setting.json` file is displayed.
 
 . Add a new plug-in registry using the `chePlugins.repositories` attribute as shown below:
 +
-[source,yaml]
+[source,yaml,subs="+macros,attributes"]
 ----
 {
 “application.confirmExit”: “never”,
-“chePlugins.repositories”: {“test”: “++https++://test.com”}
+“chePlugins.repositories”: {“test”: “pass:c,m,a,q[+https+://test.com]”}
 }
 ----
 

modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc

@@ -12,7 +12,7 @@ pass:[<!-- vale IBM.Headings = YES -->]
 This procedure describes how to activate OAuth 1 for Bitbucket Server to:
 
 * Use devfiles hosted on a Bitbucket Server.
-* xref:end-user-guide:authentication-against-bitbucket-server-with-the-personal-access-token.adoc[].
+* xref:end-user-guide:authenticating-on-scm-server-with-a-personal-access-token.adoc[].
 
 It enables {prod-short} to obtain and renew link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Bitbucket Server Personal access tokens].
 
@@ -121,4 +121,4 @@ Public Key:: Paste the content of the `__<public-stripped.pub>__` file.
 * link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Bitbucket Server Personal access tokens]
 * link:https://confluence.atlassian.com/jirakb/how-to-generate-public-key-to-application-link-3rd-party-applications-913214098.html[How to generate public key to application link 3rd party applications]
 * link:https://confluence.atlassian.com/adminjiraserver/using-applinks-to-link-to-other-applications-938846918.html[Using AppLinks to link to other applications]
-* xref:end-user-guide:authentication-against-bitbucket-server-with-the-personal-access-token.adoc[].
+* xref:end-user-guide:authenticating-on-scm-server-with-a-personal-access-token.adoc[].

modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc

@@ -0,0 +1,35 @@
+pass:[<!-- vale Vale.Spelling = NO -->]
+
+pass:[<!-- vale Vale.Terms = NO -->]
+
+pass:[<!-- vale IBM.Usage = NO -->]
+
+pass:[<!-- vale IBM.PassiveVoice = NO -->]
+
+pass:[<!-- vale IBM.Slash = NO -->]
+
+apiVersion: v1
+kind: Secret
+metadata:
+  name: gitlab-personal-access-token-secret
+  labels:
+    app.kubernetes.io/part-of: che.eclipse.org
+    app.kubernetes.io/component: scm-personal-access-token
+  annotations:
+    che.eclipse.org/expired-after: '-1'
+    che.eclipse.org/che-userid: '355d1ce5-990e-401e-9a8c-094bca10b5b3'
+    che.eclipse.org/scm-userid: '2'
+    che.eclipse.org/scm-username: 'user-foo'
+    che.eclipse.org/scm-url: 'https://gitlab.apps.cluster-example.com'
+data:
+  token: Yzh5cEt6cURxUWVCa3FKazhtaHg=
+
+pass:[<!-- vale Vale.Spelling = YES -->]
+
+pass:[<!-- vale Vale.Terms = YES -->]
+
+pass:[<!-- vale IBM.Usage = YES -->]
+
+pass:[<!-- vale IBM.PassiveVoice = YES -->]
+
+pass:[<!-- vale IBM.Slash = YES -->]

modules/end-user-guide/nav.adoc

@@ -21,7 +21,7 @@
 ** xref:importing-kubernetes-applications-into-a-workspace.adoc[]
 ** xref:remotely-accessing-workspaces.adoc[]
 ** xref:mounting-a-secret-as-a-file-or-an-environment-variable-into-a-workspace-container.adoc[]
-** xref:authentication-against-bitbucket-server-with-the-personal-access-token.adoc[]
+** xref:authenticating-on-scm-server-with-a-personal-access-token.adoc[]
 * xref:customizing-developer-environments.adoc[]
 ** xref:what-is-a-che-theia-plug-in.adoc[]
 ** xref:adding-a-vs-code-extension-to-a-workspace.adoc[]

modules/end-user-guide/pages/authenticating-on-scm-server-with-a-personal-access-token.adoc

@@ -0,0 +1,7 @@
+[id="authenticating-on-scm-server-with-a-personal-access-token"]
+// = Authenticating on scm server with a personal access token
+:navtitle: Authenticating on SCM Server with a personal access token
+:keywords: end-user-guide, authentication-on-scm-server-with-a-personal-access-token
+:page-aliases: .:authenticating-on-scm-server-with-a-personal-access-token
+
+include::partial$assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc[]

modules/end-user-guide/partials/assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc

@@ -0,0 +1,22 @@
+
+
+:parent-context-of-authenticating-on-scm-server-with-a-personal-access-token: {context}
+
+[id="authenticating-on-scm-server-with-a-personal-access-token_{context}"]
+= Authenticating users on private repositories of SCM servers
+
+
+The following section describes how to configure user authentications for SCM servers.
+
+* xref:configuring_gitlab_authentication_{context}[]
+
+* xref:configuring_bitbucket_authentication_{context}[]
+
+
+
+include::partial$proc_configuring_bitbucket_authentication.adoc[leveloffset=+1]
+
+include::partial$proc_configuring_gitlab_authentication.adoc[leveloffset=+1]
+
+
+:context: {parent-context-of-authenticating-on-scm-server-with-a-personal-access-token}

modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc

@@ -1,18 +1,18 @@
-// configuring-bitbucket-authentication
+// Module included in the following assemblies:
+//
+// authenticating-on-scm-server-with-a-personal-access-token
 
 [id="configuring_bitbucket_authentication_{context}"]
 = Authenticating on Bitbucket servers
 
 {prod} users may use public or private repositories on Bitbucket SCM (Source Code Management) system as a source of their projects.
 
-The use of private repositories, requires some additional configuration described below.
+The use of private repositories requires additional configuration described below.
 
-Bitbucket authentication is based on using personal access tokens. Each Bitbucket user is able to request some
-amount of personal access tokens with different names, permissions, expiration times, and so on. Those tokens
-can be used to sign Bitbucket REST API calls and perform Git repository operations.
+Bitbucket authentication is based on using personal access tokens. Each Bitbucket user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign Bitbucket REST API calls and perform Git repository operations.
 
-To allow Bitbucket authentication on {prod} side, personal tokens must be stored in user's namespace in a form of
-secret. The secret must look as follows:
+To allow Bitbucket authentication on {prod-short} side, personal tokens must be stored in the user's namespace in the form of
+a secret. The secret must look as follows:
 
 [source,yaml]
 ----
@@ -58,19 +58,18 @@ NOTE: Encoding a string into the base64 format using the `base64` tool on Linux
 . To obtain a user ID from a secret using a call to a REST API URL:
 *  For Bitbucket:
 +
-[subs="+quotes"]
+[subs="+quotes,macros"]
 ----
-https://__<bitbucket-hostname>__/rest/api/1.0/users/__<username>__
+++https++://__<bitbucket-hostname>__/rest/api/1.0/users/__<username>__
 ----
 
 * For {prod-short}
 +
-[subs="+attributes,+quotes"]
+[subs="+macros,attributes"]
 ----
 {prod-url}/api/user
 ----
 
 * With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.
 
-* When a remote Git repository uses a self-signed certificate, add an additional server configuration. See:
-xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[].
+* When a remote Git repository uses a self-signed certificate, add an additional server configuration. See xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[].

modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc

@@ -0,0 +1,76 @@
+// Module included in the following assemblies:
+//
+// authenticating-on-scm-server-with-a-personal-access-token
+
+[id="configuring_gitlab_authentication_{context}"]
+= Authenticating on GitLab servers
+
+Configuring authentication on the GitLab system is similar to Bitbucket.
+
+GitLab authentication is based on using personal access tokens. Each GitLab user is able to request several personal access tokens with different names, permissions, expiration times, and so on. Those tokens can be used to sign GitLab REST API calls and perform Git repository operations.
+
+See the link:https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens[GitLab documentation] for more details about personal access tokens.
+
+To allow GitLab authentication on {prod-short} side, personal tokens must be stored in the user's namespace in the form of
+a secret. The secret must look as follows:
+
+[source,yaml]
+----
+include::example$snip_gitlab-personal-access-token-secret.adoc[]
+----
+
+The main parts of the secret are:
+
+[cols=3*]
+|===
+| Label
+| `app.kubernetes.io/component`
+| Indicates it is a SCM personal token secret. 
+
+| Annotation
+| `che.eclipse.org/che-userid`
+| {prod} id of the user token belongs to
+
+| Annotation
+| `che.eclipse.org/scm-userid`
+| GitLab user id to which token belongs
+
+| Annotation
+| `che.eclipse.org/scm-username`
+| GitlLab user name to which token belongs
+
+| Annotation
+| `che.eclipse.org/scm-url`
+| GitLab server URL to which this token belong
+
+| Annotation
+| `che.eclipse.org/expired-after`
+| Personal access token expiration time
+
+| Data entry
+| `token`
+| Base-64 encoded value of the personal access token
+
+|===
+
+NOTE: Encoding a string into the base64 format using the `base64` tool on Linux machines leads to adding the newline character to the end of the source string and causing a value to be unusable as the authentication header value after decoding. Avoid this by using `base64 -w0`, which removes newly added lines, or strip newlines explicitly using`tr -d \\n`.
+
+. To obtain a user ID from a secret, take a look into user profile page on GitLab web UI or make a call to a REST API URL:
+*  For GitLab:
++
+[subs="+quotes,macros"]
+----
+++https++://__<gitlab-hostname>__/api/v4/users?username=__<username>__
+----
+
+* For {prod-short}
++
+[subs="+macros,attributes"]
+----
+{prod-url}/api/user
+----
+
+* With the token credentials obtained from a secret, another secret is automatically created, allowing authorization to Git operations. This secret is mounted into a workspace container as a Git credentials file, and any additional configurations are not required to work with private Git repositories.
+
+* When a remote Git repository uses a self-signed certificate, add an additional server configuration. See:
+xref:installation-guide:deploying-che-with-support-for-git-repositories-with-self-signed-certificates.adoc[].