diff --git a/modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc b/modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc index a2d041e98c..d91502d427 100644 --- a/modules/administration-guide/partials/proc_adding-a-custom-plug-in-registry-in-an-existing-che-workspace.adoc +++ b/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]”} } ---- diff --git a/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc b/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc index 8fcf31d5e4..9d30f3be12 100644 --- a/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc +++ b/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc @@ -12,7 +12,7 @@ pass:[] 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 `____` 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[]. diff --git a/modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc b/modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc new file mode 100644 index 0000000000..38f644a66d --- /dev/null +++ b/modules/end-user-guide/examples/snip_gitlab-personal-access-token-secret.adoc @@ -0,0 +1,35 @@ +pass:[] + +pass:[] + +pass:[] + +pass:[] + +pass:[] + +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:[] + +pass:[] + +pass:[] + +pass:[] + +pass:[] \ No newline at end of file diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 90ce6c26a1..0019ca4d65 100644 --- a/modules/end-user-guide/nav.adoc +++ b/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[] diff --git a/modules/end-user-guide/pages/authenticating-on-scm-server-with-a-personal-access-token.adoc b/modules/end-user-guide/pages/authenticating-on-scm-server-with-a-personal-access-token.adoc new file mode 100644 index 0000000000..a881291895 --- /dev/null +++ b/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[] diff --git a/modules/end-user-guide/pages/authentication-against-bitbucket-server-with-the-personal-access-token.adoc b/modules/end-user-guide/pages/authentication-against-bitbucket-server-with-the-personal-access-token.adoc deleted file mode 100644 index 5157807103..0000000000 --- a/modules/end-user-guide/pages/authentication-against-bitbucket-server-with-the-personal-access-token.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authentication-against-bitbucket-server-with-the-personal-access-token"] -// = Authentication against Bitbucket Server with the personal access token -:navtitle: Authentication against Bitbucket Server with the personal access token -:keywords: end-user-guide, authentication-against-bitbucket-server-with-the-personal-access-token -:page-aliases: .:authentication-against-bitbucket-server-with-the-personal-access-token - -include::partial$proc_configuring_bitbucket_authentication.adoc[] diff --git a/modules/end-user-guide/partials/assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc b/modules/end-user-guide/partials/assembly_authenticating-on-scm-server-with-a-personal-access-token.adoc new file mode 100644 index 0000000000..1a53823a4a --- /dev/null +++ b/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} \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc b/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc index a14d4f011b..336068cb17 100644 --- a/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc +++ b/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://____/rest/api/1.0/users/____ +++https++://____/rest/api/1.0/users/____ ---- * 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[]. \ No newline at end of file +* 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[]. \ No newline at end of file diff --git a/modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc b/modules/end-user-guide/partials/proc_configuring_gitlab_authentication.adoc new file mode 100644 index 0000000000..39263367ea --- /dev/null +++ b/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++://____/api/v4/users?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[]. \ No newline at end of file