Obtain and persist Bitbucket personal access token as k8s secret (#1807)

Obtain and persist Bitbucket personal access token as k8s secret (#1807)
Signed-off-by: Sergii Kabashniuk <skabashniuk@redhat.com>
Co-authored-by: Fabrice Flore-Thébault <ffloreth@redhat.com>
Co-authored-by: Serhii Leshchenko <sleshche@redhat.com>

.vale.ini

@@ -1,5 +1,5 @@
-# Vale configuration file, taken from https://errata-ai.github.io/vale/config/
-
+# Vale configuration file, taken from https://docs.errata.ai/vale/config
+#
 # The relative path to the folder containing linting rules (styles)
 # -----------------------------------------------------------------
 StylesPath = .vale/styles
@@ -13,7 +13,7 @@ Vocab = Che
 # unless you execute Vale with the --no-exit flag
 MinAlertLevel = suggestion
 IgnoredScopes = code, tt, img, url, a
-SkippedScopes = script, style, pre, figure
+SkippedScopes = script, style, pre, figure, code, tt
 
 
 # What file types should Vale test?

.vale/styles/CheDocs/CommonTerms.yml

@@ -4,10 +4,10 @@ message: Consider using '%s' instead of '%s'
 ignorecase: false
 level: warning
 swap:
-  '\sche': '{prod-short}'
-  '\sChe': '{prod-short}'
+  '\sche': "{prod-short}"
+  '\sChe': "{prod-short}"
   '\sContainer Registry': Red Hat Ecosystem Catalog
-  '\sContainer Catalog': Red Hat Ecosystem Catalog 
+  '\sContainer Catalog': Red Hat Ecosystem Catalog
   '\s[^n] binary': tool
   '\sconfig map': ConfigMap
   '\sconfig maps': ConfigMaps

.vale/styles/Vocab/Che/accept.txt

@@ -2,30 +2,26 @@
 adoc
 Antora
 API
-Asciidoc
+AsciiDoc
 AWS
-boolean
-Boolean
+Bitbucket
+boolean|Boolean
 breakpoint
 btn
 Btrfs
 CentOS
-CentOS
 Ceph
 Che-Theia
-Che-Theia
-Classloading|classloading
+classloading|Classloading
 ConfigMap
 ConfigMaps
 DaemonSet
-DaemonSet
 Developer Perspective
 devfile
 devfiles
 DNS
 Docker
 Dockerfile
-Dockerfile
 Dotnet
 Endevor
 endif

modules/administration-guide/nav.adoc

@@ -10,13 +10,6 @@
 ** xref:building-custom-registry-images.adoc[]
 ** xref:running-custom-registries.adoc[]
 
-* xref:managing-users.adoc[]
-** xref:authenticating-users.adoc[]
-** xref:authorizing-users.adoc[]
-** xref:configuring-authorization.adoc[]
-** xref:removing-user-data.adoc[]
-** xref:authenticating-users-3rd-party-services.adoc[]
-
 * xref:retrieving-che-logs.adoc[]
 ** xref:configuring-server-logging.adoc[]
 ** xref:viewing-kubernetes-events.adoc[]
@@ -41,3 +34,10 @@
 ** xref:installing-image-puller-on-openshift-using-operatorhub.adoc[]
 ** xref:installing-image-puller-on-openshift-using-openshift-templates.adoc[]
 ** xref:installing-image-puller-on-kubernetes-using-helm.adoc[]
+
+* xref:managing-identities-and-authorizations.adoc[]
+** xref:authenticating-users.adoc[]
+** xref:authorizing-users.adoc[]
+** xref:configuring-authorization.adoc[]
+** xref:configuring-openshift-oauth.adoc[]
+** xref:removing-user-data.adoc[]

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

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

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

@@ -19,6 +19,8 @@ include::partial$proc_enabling-authentication-with-social-accounts-and-brokering
 
 include::partial$proc_configuring-github-oauth.adoc[leveloffset=+2]
 
+include::partial$proc_configuring-bitbucket-server-oauth1.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/assembly_managing-identities-and-authorizations.adoc

@@ -0,0 +1,18 @@
+
+
+:parent-context-of-configuring-oauth-authorization: {context}
+
+[id="managing-identities-and-authorizations_{context}"]
+= Managing identities and authorizations
+
+:context: managing-identities-and-authorizations
+
+This section describes different aspects of managing identities and authorizations of {prod}.
+
+* xref:authenticating-users.adoc[]
+* xref:authorizing-users.adoc[]
+* xref:configuring-authorization.adoc[]
+* xref:removing-user-data.adoc[]
+* xref:configuring-openshift-oauth.adoc[]
+
+:context: {parent-context-of-managing-identities-and-authorizations}

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

@@ -0,0 +1,140 @@
+// Module included in the following assemblies:
+//
+// Configuring Bitbucket server OAuth1
+
+pass:[<!-- vale IBM.Headings = NO -->]
+
+[id="proc_configuring-bitbucket-server-oauth1_{context}"]
+= Configuring Bitbucket Server OAuth 1
+
+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[].
+
+It enables {prod-short} to obtain and renew link:https://confluence.atlassian.com/bitbucketserver/personal-access-tokens-939515499.html[Bitbucket Server Personal access tokens].
+
+.Prerequisites
+
+* The `{orch-cli}` tool is available.
+* Bitbucket Server is available from {prod-short} server.
+
+.Procedure
+
+. Generate a RSA key pair and a stripped down version of the public key: 
++
+[subs="+quotes,+attributes"]
+----
+openssl genrsa -out __<private.pem>__ 2048
+openssl rsa -in __<private.pem>__ -pubout > __<public.pub>__
+openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in __<private.pem>__ -out __<privatepkcs8.pem>__
+cat __<public.pub>__ | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > __<public-stripped.pub>__
+----
+
+. Generate a consumer key and a shared secret.
++
+[subs="+quotes,+attributes"]
+----
+openssl rand -base64 24 > __<bitbucket_server_consumer_key>__
+openssl rand -base64 24 > __<bitbucket_shared_secret>__
+----
+
+. Create a Kubernetes Secret in {prod-short} namespace containing the RSA key pair, the consumer key and the shared secret.
++
+[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: che-secret
+  annotations:
+    che.eclipse.org/mount-path: /home/user/eclipse-che/conf/oauth1/bitbucket
+    che.eclipse.org/mount-as: file
+data:
+  private.key: <...> <2>
+  consumer.key: <...> <3>
+  shared_secret: <...> <4>
+type: Opaque
+EOF
+----
+<1> {prod-short} namespace. The default is {prod-namespace}
+<2> base64 encoded content of the __<privatepkcs8.pem>__ file without first and last lines.
+<3> base64 encoded content of the `__<bitbucket_server_consumer_key>__` file.
+<4> base64 encoded content of the `__<bitbucket_shared_secret>__` file.
+
+. Configure the {prod-short} server environment variables:
++
+[subs="+quotes,macros"]
+----
+spec:
+ server:
+   customCheProperties:
+     pass:[CHE_OAUTH1_BITBUCKET_CONSUMERKEYPATH]: '/home/user/eclipse-che/conf/oauth1/bitbucket/consumer.key'
+     pass:[CHE_OAUTH1_BITBUCKET_SHAREDSECRETPATH]: '/home/user/eclipse-che/conf/oauth1/bitbucket/shared_secret'
+     pass:[CHE_OAUTH1_BITBUCKET_PRIVATEKEYPATH]: '/home/user/eclipse-che/conf/oauth1/bitbucket/private.key'
+     pass:[CHE_OAUTH1_BITBUCKET_ENDPOINT]: '__<Bitbucket Server URL>__'
+     pass:[CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS]: '__<Bitbucket Server URL>__'
+
+----
+
+. Configure an link:https://confluence.atlassian.com/adminjiraserver/using-applinks-to-link-to-other-applications-938846918.html[Application Link] in Bitbucket to enable the communication from {prod-short} to Bitbucket Server.
+
+.. In Bitbucket Server, click the cog in the top navigation bar to navigate to *Administration*  > *Application Links*.
+
+pass:[<!-- vale IBM.Usage = NO -->]
+
+.. Enter the application URL: `__<{prod-url-secure}/dashboard/>__` and click the btn:[Create new link] button.
+
+pass:[<!-- vale IBM.Usage = YES -->]
+
+pass:[<!-- vale IBM.PassiveVoice = NO -->]
+
+.. On the warning message stating "No response was received from the URL" click the btn:[Continue] button.
+
+pass:[<!-- vale IBM.PassiveVoice = YES -->]
+
+.. Fill-in the *Link Applications* form and click the btn:[Continue] button.
+
+Application Name::  `__<{prod-short}>__`
+
+Application Type:: Generic Application.
+
+Service Provider Name:: `__<{prod-short}>__`
+
+Consumer Key:: Paste the content of the `__<bitbucket_server_consumer_key>__` file.
+
+Shared secret:: Paste the content of the `__<bitbucket_shared_secret>__` file.
+
+Request Token URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/request-token`
+
+Access token URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/access-token`
+
+Authorize URL:: `__<Bitbucket Server URL>__/plugins/servlet/oauth/access-token`
+
+Create incoming link:: Enabled.
+
+.. Fill-in the *Link Applications* form and click the btn:[Continue] button.
+
+Consumer Key::  Paste the content of the `__<bitbucket_server_consumer_key>__` file.
+
+Consumer name::  `__<{prod-short}>__`
+
+Public Key:: Paste the content of the `__<public-stripped.pub>__` file.
+
+
+
+.Additional resources
+
+* link:https://bitbucket.org/product/enterprise[Bitbucket Server overview]
+* link:https://bitbucket.org/product/download[Download Bitbucket Server]
+* 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[].

modules/end-user-guide/nav.adoc

@@ -19,6 +19,7 @@
 ** xref:creating-a-workspace-from-code-sample.adoc[]
 ** xref:creating-a-workspace-by-importing-source-code-of-a-project.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:customizing-developer-environments.adoc[]
 ** xref:what-is-a-che-theia-plug-in.adoc[]
 ** xref:adding-a-vs-code-extension-to-a-workspace.adoc[]
@@ -31,8 +32,6 @@
 **** xref:using-jetbrains-webstorm.adoc[]
 **** xref:provisioning-jetbrains-activation-code-for-offline-use.adoc[]
 ** xref:adding-tools-to-che-after-creating-a-workspace.adoc[]
-* xref:configuring-oauth-authorization.adoc[]
-** xref:configuring-openshift-oauth.adoc[]
 * xref:using-artifact-repositories-in-a-restricted-environment.adoc[]
 ** xref:using-maven-artifact-repositories.adoc[]
 ** xref:using-gradle-artifact-repositories.adoc[]

modules/end-user-guide/pages/authentication-against-bitbucket-server-with-the-personal-access-token.adoc

@@ -0,0 +1,7 @@
+[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[]

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

@@ -1,10 +1,9 @@
 // configuring-bitbucket-authentication
 
 [id="configuring_bitbucket_authentication_{context}"]
-= Authentication on Bitbucket servers
+= Authenticating on Bitbucket servers
 
-{prod} users may use public or private repositories Bitbucket SCM (Source Code Management) system as a source of their projects. The standard
-factory flow using devfile at the root of the repository is available starting of 7.25 version of {prod}.
+{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.
 

modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc

@@ -33,7 +33,7 @@ When using a local instance of OpenShift (such as CodeReady Containers or Minish
 * A running instance of {prod-short}. To install an instance of {prod-short}, see xref:installation-guide:installing-che.adoc[].
 * A {prod-short} workspace has been created.
 * The OpenShift Connector plug-in is available.
-* The OpenShift OAuth provider is configured (only for the auto-login to the OpenShift cluster where {prod-short} is deployed. See xref:end-user-guide:configuring-openshift-oauth.adoc[]).
+* The OpenShift OAuth provider is configured (only for the auto-login to the OpenShift cluster where {prod-short} is deployed. See xref:administration-guide:configuring-openshift-oauth.adoc[]).
 
 .Procedure