From ed593d1fa31783ad036f0cf5f985e3fbbbfcf670 Mon Sep 17 00:00:00 2001 From: Igor Vinokur Date: Mon, 5 Sep 2022 16:59:49 +0300 Subject: [PATCH] chore: Add documentation pages for the Bitbucket SAAS OAuth flow (#2410) Add instructions how to configure Bitbucket SAAS OAuth flow --- modules/administration-guide/nav.adoc | 3 +- ...guring-oauth-1-for-a-bitbucket-server.adoc | 17 ++++++ .../configuring-oauth-1-for-bitbucket.adoc | 17 ------ ...uring-oauth-2-for-the-bitbucket-cloud.adoc | 17 ++++++ .../oauth-for-github-gitlab-or-bitbucket.adoc | 4 +- ...link-secret-for-the-bitbucket-server.adoc} | 18 +++--- ...nsumer-secret-for-the-bitbucket-cloud.adoc | 56 +++++++++++++++++++ ...ication-link-on-the-bitbucket-server.adoc} | 16 +++--- ...oauth-consumer-in-the-bitbucket-cloud.adoc | 47 ++++++++++++++++ 9 files changed, 158 insertions(+), 37 deletions(-) create mode 100644 modules/administration-guide/pages/configuring-oauth-1-for-a-bitbucket-server.adoc delete mode 100644 modules/administration-guide/pages/configuring-oauth-1-for-bitbucket.adoc create mode 100644 modules/administration-guide/pages/configuring-oauth-2-for-the-bitbucket-cloud.adoc rename modules/administration-guide/partials/{proc_applying-the-bitbucket-application-link-secret.adoc => proc_applying-an-application-link-secret-for-the-bitbucket-server.adoc} (72%) create mode 100644 modules/administration-guide/partials/proc_applying-an-oauth-consumer-secret-for-the-bitbucket-cloud.adoc rename modules/administration-guide/partials/{proc_setting-up-the-bitbucket-application-link.adoc => proc_setting-up-an-application-link-on-the-bitbucket-server.adoc} (82%) create mode 100644 modules/administration-guide/partials/proc_setting-up-an-oauth-consumer-in-the-bitbucket-cloud.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 0a9806ada0..cf39794706 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -68,7 +68,8 @@ *** xref:oauth-for-github-gitlab-or-bitbucket.adoc[] **** xref:configuring-oauth-2-for-github.adoc[] **** xref:configuring-oauth-2-for-gitlab.adoc[] -**** xref:configuring-oauth-1-for-bitbucket.adoc[] +**** xref:configuring-oauth-1-for-a-bitbucket-server.adoc[] +**** xref:configuring-oauth-2-for-the-bitbucket-cloud.adoc[] *** xref:configuring-the-administrative-user.adoc[] *** xref:removing-user-data.adoc[] * xref:managing-workloads-using-the-che-server-api.adoc[] diff --git a/modules/administration-guide/pages/configuring-oauth-1-for-a-bitbucket-server.adoc b/modules/administration-guide/pages/configuring-oauth-1-for-a-bitbucket-server.adoc new file mode 100644 index 0000000000..95ab643250 --- /dev/null +++ b/modules/administration-guide/pages/configuring-oauth-1-for-a-bitbucket-server.adoc @@ -0,0 +1,17 @@ +:_content-type: ASSEMBLY +:description: Configuring OAuth 1.0 for a Bitbucket Server +:keywords: configuring-oauth, authorization, bitbucket, bitbucket-server, oauth-1, oauth-1.0 +:navtitle: Configuring OAuth 1.0 for a Bitbucket Server +// :page-aliases: + +[id="configuring-oauth-1-for-a-bitbucket-server_{context}"] += Configuring OAuth 1.0 for a Bitbucket Server + +To enable users to work with a remote Git repository that is hosted on a Bitbucket Server: + +. Set up an application link (OAuth 1.0) on the Bitbucket Server. +. Apply an application link Secret for the Bitbucket Server. + +include::partial$proc_setting-up-an-application-link-on-the-bitbucket-server.adoc[leveloffset=+1] + +include::partial$proc_applying-an-application-link-secret-for-the-bitbucket-server.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/configuring-oauth-1-for-bitbucket.adoc b/modules/administration-guide/pages/configuring-oauth-1-for-bitbucket.adoc deleted file mode 100644 index 7c75d46338..0000000000 --- a/modules/administration-guide/pages/configuring-oauth-1-for-bitbucket.adoc +++ /dev/null @@ -1,17 +0,0 @@ -:_content-type: ASSEMBLY -:description: Configuring OAuth 1.0 for Bitbucket -:keywords: configuring-oauth, authorization, bitbucket, oauth-1, oauth-1.0 -:navtitle: Configuring OAuth 1.0 for Bitbucket -:page-aliases: - -[id="configuring-oauth-1-for-bitbucket_{context}"] -= Configuring OAuth 1.0 for Bitbucket - -To enable users to work with a remote Git repository that is hosted on a Bitbucket server: - -. Set up the Bitbucket application link (OAuth 1.0). -. Apply the Bitbucket application link Secret. - -include::partial$proc_setting-up-the-bitbucket-application-link.adoc[leveloffset=+1] - -include::partial$proc_applying-the-bitbucket-application-link-secret.adoc[leveloffset=+1] diff --git a/modules/administration-guide/pages/configuring-oauth-2-for-the-bitbucket-cloud.adoc b/modules/administration-guide/pages/configuring-oauth-2-for-the-bitbucket-cloud.adoc new file mode 100644 index 0000000000..dafa1dd109 --- /dev/null +++ b/modules/administration-guide/pages/configuring-oauth-2-for-the-bitbucket-cloud.adoc @@ -0,0 +1,17 @@ +:_content-type: ASSEMBLY +:description: Configuring OAuth 2.0 for the Bitbucket Cloud +:keywords: configuring-oauth, authorization, bitbucket, bitbucket-cloud, cloud, oauth-2, oauth-2.0 +:navtitle: Configuring OAuth 2.0 for the Bitbucket Cloud +// :page-aliases: + +[id="configuring-oauth-2-for-the-bitbucket-cloud_{context}"] += Configuring OAuth 2.0 for the Bitbucket Cloud + +You can enable users to work with a remote Git repository that is hosted in the Bitbucket Cloud: + +. Set up an OAuth consumer (OAuth 2.0) in the Bitbucket Cloud. +. Apply an OAuth consumer Secret for the Bitbucket Cloud. + +include::partial$proc_setting-up-an-oauth-consumer-in-the-bitbucket-cloud.adoc[leveloffset=+1] + +include::partial$proc_applying-an-oauth-consumer-secret-for-the-bitbucket-cloud.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/administration-guide/pages/oauth-for-github-gitlab-or-bitbucket.adoc b/modules/administration-guide/pages/oauth-for-github-gitlab-or-bitbucket.adoc index b1af6c93fd..829e2060dc 100644 --- a/modules/administration-guide/pages/oauth-for-github-gitlab-or-bitbucket.adoc +++ b/modules/administration-guide/pages/oauth-for-github-gitlab-or-bitbucket.adoc @@ -2,7 +2,7 @@ :description: OAuth for GitHub, GitLab, or Bitbucket :keywords: bitbucket :navtitle: OAuth for GitHub, GitLab, or Bitbucket -:page-aliases: +// :page-aliases: [id="oauth-for-github-gitlab-or-bitbucket_{context}"] = OAuth for GitHub, GitLab, or Bitbucket @@ -11,4 +11,4 @@ To enable users to work with remote Git repositories: * xref:configuring-oauth-2-for-github.adoc[] * xref:configuring-oauth-2-for-gitlab.adoc[] -* xref:configuring-oauth-1-for-bitbucket.adoc[] +* Configuring xref:configuring-oauth-1-for-a-bitbucket-server.adoc[OAuth 1.0 for a Bitbucket Server] or xref:configuring-oauth-2-for-the-bitbucket-cloud.adoc[OAuth 2.0 for the Bitbucket Cloud] diff --git a/modules/administration-guide/partials/proc_applying-the-bitbucket-application-link-secret.adoc b/modules/administration-guide/partials/proc_applying-an-application-link-secret-for-the-bitbucket-server.adoc similarity index 72% rename from modules/administration-guide/partials/proc_applying-the-bitbucket-application-link-secret.adoc rename to modules/administration-guide/partials/proc_applying-an-application-link-secret-for-the-bitbucket-server.adoc index c4cd6e4c62..ce355da8a1 100644 --- a/modules/administration-guide/partials/proc_applying-the-bitbucket-application-link-secret.adoc +++ b/modules/administration-guide/partials/proc_applying-an-application-link-secret-for-the-bitbucket-server.adoc @@ -1,19 +1,19 @@ :_content-type: PROCEDURE -:description: Applying the Bitbucket application link Secret -:keywords: bitbucket, bitbucket-application, bitbucket-app, bitbucket-application-link, bitbucket-app-link, bitbucket-secret, secret -:navtitle: Applying the Bitbucket application link Secret +:description: Applying an application link Secret for the Bitbucket Server +:keywords: bitbucket, bitbucket-server, application-link, bitbucket-secret +:navtitle: Applying an application link Secret for the Bitbucket Server // :page-aliases: -[id="applying-the-bitbucket-application-link-secret_{context}"] -= Applying the Bitbucket application link Secret +[id="applying-an-application-link-secret-for-the-bitbucket-server_{context}"] += Applying an application link Secret for the Bitbucket Server -Prepare and apply the Bitbucket application link Secret. +Prepare and apply the application link Secret for the Bitbucket Server. .Prerequisites -* Setting up the Bitbucket application link is completed. +* The application link is set up on the Bitbucket Server. -* The following Base64-encoded files, which were created when setting up the Bitbucket application link, are prepared: +* The following Base64-encoded files, which were created when setting up the application link, are prepared: ** `privatepkcs8-stripped.pem` ** `bitbucket_consumer_key` ** `bitbucket-shared-secret` @@ -44,7 +44,7 @@ data: shared_secret: ____ <5> ---- <1> The {prod-short} namespace. The default is `{prod-namespace}`. -<2> The Bitbucket server URL. +<2> The URL of the Bitbucket Server. <3> The Base64-encoded content of the `privatepkcs8-stripped.pem` file. <4> The Base64-encoded content of the `bitbucket_consumer_key` file. <5> The Base64-encoded content of the `bitbucket-shared-secret` file. diff --git a/modules/administration-guide/partials/proc_applying-an-oauth-consumer-secret-for-the-bitbucket-cloud.adoc b/modules/administration-guide/partials/proc_applying-an-oauth-consumer-secret-for-the-bitbucket-cloud.adoc new file mode 100644 index 0000000000..c366f2181d --- /dev/null +++ b/modules/administration-guide/partials/proc_applying-an-oauth-consumer-secret-for-the-bitbucket-cloud.adoc @@ -0,0 +1,56 @@ +:_content-type: PROCEDURE +:description: Applying an OAuth consumer Secret for the Bitbucket Cloud +:keywords: bitbucket, bitbucket-cloud, oauth-consumer, bitbucket-consumer, oauth-consumer-secret, bitbucket-client-secret +:navtitle: Applying an OAuth consumer Secret for the Bitbucket Cloud +// :page-aliases: + +[id="applying-an-oauth-consumer-secret-for-the-bitbucket-cloud_{context}"] += Applying an OAuth consumer Secret for the Bitbucket Cloud + +Prepare and apply an OAuth consumer Secret for the Bitbucket Cloud. + +.Prerequisites + +* The OAuth consumer is set up in the Bitbucket Cloud. + +* The Base64-encoded values, which were generated when setting up the Bitbucket OAuth consumer, are prepared: +** Bitbucket OAuth consumer Key +** Bitbucket OAuth consumer Secret + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. + +.Procedure + +. Prepare the Secret: ++ +[source,yaml,subs="+quotes,+attributes,+macros"] +---- +kind: Secret +apiVersion: v1 +metadata: + name: bitbucket-oauth-config + namespace: {prod-namespace} <1> + labels: + app.kubernetes.io/part-of: che.eclipse.org + app.kubernetes.io/component: oauth-scm-configuration + annotations: + che.eclipse.org/oauth-scm-server: bitbucket +type: Opaque +data: + id: ____ <2> + secret: ____ <3> +---- +<1> The {prod-short} namespace. The default is `{prod-namespace}`. +<2> The Base64-encoded *Bitbucket OAuth consumer Key*. +<3> The Base64-encoded *Bitbucket OAuth consumer Secret*. + +. Apply the Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ {orch-cli} apply -f - <__ +EOF +---- + +. Verify in the output that the Secret is created. \ No newline at end of file diff --git a/modules/administration-guide/partials/proc_setting-up-the-bitbucket-application-link.adoc b/modules/administration-guide/partials/proc_setting-up-an-application-link-on-the-bitbucket-server.adoc similarity index 82% rename from modules/administration-guide/partials/proc_setting-up-the-bitbucket-application-link.adoc rename to modules/administration-guide/partials/proc_setting-up-an-application-link-on-the-bitbucket-server.adoc index 8ed560bede..3ae8d03503 100644 --- a/modules/administration-guide/partials/proc_setting-up-the-bitbucket-application-link.adoc +++ b/modules/administration-guide/partials/proc_setting-up-an-application-link-on-the-bitbucket-server.adoc @@ -1,23 +1,23 @@ :_content-type: PROCEDURE -:description: Setting up the Bitbucket application link -:keywords: bitbucket, bitbucket-application-link, application-link -:navtitle: Setting up the Bitbucket application link +:description: Setting up an application link on the Bitbucket Server +:keywords: bitbucket, bitbucket-server, application-link +:navtitle: Setting up an application link on the Bitbucket Server // :page-aliases: -[id="setting-up-the-bitbucket-application-link_{context}"] -= Setting up the Bitbucket application link +[id="setting-up-an-application-link-on-the-bitbucket-server_{context}"] += Setting up an application link on the Bitbucket Server -Set up a Bitbucket application link using OAuth 1.0. +Set up an application link for OAuth 1.0 on the Bitbucket Server. .Prerequisites -* You are logged in to Bitbucket. +* You are logged in to the Bitbucket Server. * link:https://www.openssl.org/[`openssl`] is installed in the operating system you are using. * link:https://www.gnu.org/software/coreutils/base64[`base64`] is installed in the operating system you are using. .Procedure -. On a command line, run the commands to create the necessary files for the next steps and for use when applying the Bitbucket application link Secret: +. On a command line, run the commands to create the necessary files for the next steps and for use when applying the application link Secret: + [subs="+quotes,+attributes,+macros"] ---- diff --git a/modules/administration-guide/partials/proc_setting-up-an-oauth-consumer-in-the-bitbucket-cloud.adoc b/modules/administration-guide/partials/proc_setting-up-an-oauth-consumer-in-the-bitbucket-cloud.adoc new file mode 100644 index 0000000000..e99e384d73 --- /dev/null +++ b/modules/administration-guide/partials/proc_setting-up-an-oauth-consumer-in-the-bitbucket-cloud.adoc @@ -0,0 +1,47 @@ +:_content-type: PROCEDURE +:description: Setting up an OAuth consumer in the Bitbucket Cloud +:keywords: bitbucket, bitbucket-cloud, oauth-consumer, bitbucket-oauth-consumer, oauth-application +:navtitle: Setting up an OAuth consumer in the Bitbucket Cloud +// :page-aliases: + +[id="setting-up-an-oauth-consumer-in-the-bitbucket-cloud_{context}"] += Setting up an OAuth consumer in the Bitbucket Cloud + +Set up an OAuth consumer for OAuth 2.0 in the Bitbucket Cloud. + +.Prerequisites + +* You are logged in to the Bitbucket Cloud. +* link:https://www.gnu.org/software/coreutils/base64[`base64`] is installed in the operating system you are using. + +.Procedure + +. Click your avatar and go to the *All workspaces* page. + +. Select a workspace and click it. + +. Go to menu:Settings[OAuth consumers > Add consumer]. + +. Enter *{prod-short}* as the *Name*. + +. Enter `pass:c,a,q[{prod-url}]/api/oauth/callback` as the *Callback URL*. + +. Under *Permissions*, check all of the *Account* and *Repositories* checkboxes, and click *Save*. + +. Expand the added consumer and then copy the *Key* value and encode it to Base64 for use when applying the Bitbucket OAuth consumer Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ echo -n '____' | base64 +---- + +. Copy the *Secret* value and encode it to Base64 for use when applying the Bitbucket OAuth consumer Secret: ++ +[subs="+quotes,+attributes,+macros"] +---- +$ echo -n '____' | base64 +---- + +.Additional resources + +* link:https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud[Bitbucket Docs: Use OAuth on Bitbucket Cloud] \ No newline at end of file