diff --git a/.vale.ini b/.vale.ini index ef83225077..c26056292f 100644 --- a/.vale.ini +++ b/.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? diff --git a/.vale/styles/CheDocs/CommonTerms.yml b/.vale/styles/CheDocs/CommonTerms.yml index 62f25ab3c8..86d4645729 100644 --- a/.vale/styles/CheDocs/CommonTerms.yml +++ b/.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 diff --git a/.vale/styles/Vocab/Che/accept.txt b/.vale/styles/Vocab/Che/accept.txt index 2dcbb123cd..67e73559cb 100644 --- a/.vale/styles/Vocab/Che/accept.txt +++ b/.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 diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index b9443c0e28..381fc39d18 100644 --- a/modules/administration-guide/nav.adoc +++ b/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[] diff --git a/modules/administration-guide/pages/authenticating-users-3rd-party-services.adoc b/modules/administration-guide/pages/authenticating-users-3rd-party-services.adoc deleted file mode 100644 index cd51fb401b..0000000000 --- a/modules/administration-guide/pages/authenticating-users-3rd-party-services.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="authenticating-users-3rd-party-services"] -// = Authenticating users on 3-rd party services -:navtitle: Authenticating users on 3-rd party services -:keywords: administration-guide, authenticating-users -:page-aliases: .:authenticating-users-3rd party services - -include::partial$assembly_authenticating-users-on-3rd-party-services.adoc[] \ No newline at end of file diff --git a/modules/end-user-guide/pages/configuring-openshift-oauth.adoc b/modules/administration-guide/pages/configuring-openshift-oauth.adoc similarity index 100% rename from modules/end-user-guide/pages/configuring-openshift-oauth.adoc rename to modules/administration-guide/pages/configuring-openshift-oauth.adoc diff --git a/modules/administration-guide/pages/managing-identities-and-authorizations.adoc b/modules/administration-guide/pages/managing-identities-and-authorizations.adoc new file mode 100644 index 0000000000..8534724939 --- /dev/null +++ b/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[] diff --git a/modules/administration-guide/pages/managing-users.adoc b/modules/administration-guide/pages/managing-users.adoc deleted file mode 100644 index c4f4c54cef..0000000000 --- a/modules/administration-guide/pages/managing-users.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="managing-users"] -// = Managing users -:navtitle: Managing users -:keywords: administration-guide, managing-users -:page-aliases: .:managing-users, .:securing-che, securing-che - -include::partial$assembly_managing-users.adoc[] diff --git a/modules/administration-guide/partials/assembly_authenticating-users-on-3rd-party-services.adoc b/modules/administration-guide/partials/assembly_authenticating-users-on-3rd-party-services.adoc deleted file mode 100644 index e57da5f03c..0000000000 --- a/modules/administration-guide/partials/assembly_authenticating-users-on-3rd-party-services.adoc +++ /dev/null @@ -1,15 +0,0 @@ - -:parent-context-of-authorizing-users: {context} - -[id="authenticating-users-on-3rd-party-services_{context}"] -= Authenticating users on 3-rd party services - -:context: authenticating-users-on-3rd-party-services - -This topic covers authentication of users on 3-rd party services such as Bitbucket. - -include::partial$proc_configuring_bitbucket_servers.adoc[leveloffset=+1] - -include::partial$proc_configuring_bitbucket_authentication.adoc[leveloffset=+1] - -:context: {parent-context-of-authorizing-users} diff --git a/modules/administration-guide/partials/assembly_configuring-authorization.adoc b/modules/administration-guide/partials/assembly_configuring-authorization.adoc index 7473e630a6..fc12271d4a 100644 --- a/modules/administration-guide/partials/assembly_configuring-authorization.adoc +++ b/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] diff --git a/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc b/modules/administration-guide/partials/assembly_managing-identities-and-authorizations.adoc new file mode 100644 index 0000000000..87410dad18 --- /dev/null +++ b/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} diff --git a/modules/administration-guide/partials/assembly_managing-users.adoc b/modules/administration-guide/partials/assembly_managing-users.adoc deleted file mode 100644 index 9a89a218e6..0000000000 --- a/modules/administration-guide/partials/assembly_managing-users.adoc +++ /dev/null @@ -1,22 +0,0 @@ - - -:parent-context-of-managing-users: {context} - -[id="managing-users_{context}"] -= Managing users - -:context: managing-users - -This section describes how to configure authorization and authentication in {prod} and how to administer user groups and users. - -* xref:authenticating-users.adoc[] - -* xref:authorizing-users.adoc[] - -* xref:configuring-authorization.adoc[] - -* xref:removing-user-data.adoc[] - -* xref:authenticating-users-3rd-party-services.adoc[] - -:context: {parent-context-of-managing-users} diff --git a/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc b/modules/administration-guide/partials/proc_configuring-bitbucket-server-oauth1.adoc new file mode 100644 index 0000000000..e3cff19dc4 --- /dev/null +++ b/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:[] + +[id="proc_configuring-bitbucket-server-oauth1_{context}"] += Configuring Bitbucket Server OAuth 1 + +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[]. + +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 ____ 2048 +openssl rsa -in ____ -pubout > ____ +openssl pkcs8 -topk8 -inform pem -outform pem -nocrypt -in ____ -out ____ +cat ____ | sed 's/-----BEGIN PUBLIC KEY-----//g' | sed 's/-----END PUBLIC KEY-----//g' | tr -d '\n' > ____ +---- + +. Generate a consumer key and a shared secret. ++ +[subs="+quotes,+attributes"] +---- +openssl rand -base64 24 > ____ +openssl rand -base64 24 > ____ +---- + +. 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 - < <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 ____ file without first and last lines. +<3> base64 encoded content of the `____` file. +<4> base64 encoded content of the `____` 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]: '____' + pass:[CHE_INTEGRATION_BITBUCKET_SERVER__ENDPOINTS]: '____' + +---- + +. 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:[] + +.. Enter the application URL: `__<{prod-url-secure}/dashboard/>__` and click the btn:[Create new link] button. + +pass:[] + +pass:[] + +.. On the warning message stating "No response was received from the URL" click the btn:[Continue] button. + +pass:[] + +.. 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 `____` file. + +Shared secret:: Paste the content of the `____` file. + +Request Token URL:: `____/plugins/servlet/oauth/request-token` + +Access token URL:: `____/plugins/servlet/oauth/access-token` + +Authorize 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 `____` file. + +Consumer name:: `__<{prod-short}>__` + +Public Key:: Paste the content of the `____` 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[]. diff --git a/modules/end-user-guide/partials/proc_configuring-openshift-oauth.adoc b/modules/administration-guide/partials/proc_configuring-openshift-oauth.adoc similarity index 100% rename from modules/end-user-guide/partials/proc_configuring-openshift-oauth.adoc rename to modules/administration-guide/partials/proc_configuring-openshift-oauth.adoc diff --git a/modules/administration-guide/examples/snip_bitbucket-personal-access-token-secret.adoc b/modules/end-user-guide/examples/snip_bitbucket-personal-access-token-secret.adoc similarity index 100% rename from modules/administration-guide/examples/snip_bitbucket-personal-access-token-secret.adoc rename to modules/end-user-guide/examples/snip_bitbucket-personal-access-token-secret.adoc diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index b12f0ee35f..8b185983d2 100644 --- a/modules/end-user-guide/nav.adoc +++ b/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[] 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 new file mode 100644 index 0000000000..5157807103 --- /dev/null +++ b/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[] diff --git a/modules/end-user-guide/pages/configuring-oauth-authorization.adoc b/modules/end-user-guide/pages/configuring-oauth-authorization.adoc deleted file mode 100644 index a2b6ece359..0000000000 --- a/modules/end-user-guide/pages/configuring-oauth-authorization.adoc +++ /dev/null @@ -1,7 +0,0 @@ -[id="configuring-oauth-authorization"] -// = Configuring OAuth authorization -:navtitle: Configuring OAuth authorization -:keywords: end-user-guide, configuring-oauth-authorization -:page-aliases: .:configuring-oauth-authorization - -include::partial$assembly_configuring-oauth-authorization.adoc[] diff --git a/modules/end-user-guide/partials/assembly_configuring-oauth-authorization.adoc b/modules/end-user-guide/partials/assembly_configuring-oauth-authorization.adoc deleted file mode 100644 index 890bfe830f..0000000000 --- a/modules/end-user-guide/partials/assembly_configuring-oauth-authorization.adoc +++ /dev/null @@ -1,14 +0,0 @@ - - -:parent-context-of-configuring-oauth-authorization: {context} - -[id="configuring-oauth-authorization_{context}"] -= Configuring OAuth authorization - -:context: configuring-oauth-authorization - -This section describes how to connect {prod} as an OAuth application to supported OAuth providers. - -* xref:configuring-openshift-oauth.adoc[] - -:context: {parent-context-of-configuring-oauth-authorization} diff --git a/modules/administration-guide/partials/proc_configuring_bitbucket_authentication.adoc b/modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc similarity index 89% rename from modules/administration-guide/partials/proc_configuring_bitbucket_authentication.adoc rename to modules/end-user-guide/partials/proc_configuring_bitbucket_authentication.adoc index 802238b879..d5048d606d 100644 --- a/modules/administration-guide/partials/proc_configuring_bitbucket_authentication.adoc +++ b/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. diff --git a/modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc b/modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc index f4ac85692c..f0c8bfa48b 100644 --- a/modules/extensions/partials/proc_authenticating-with-openshift-connector-from-che.adoc +++ b/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