SONAR-17231 Move DevOps platform related authentication information to the newly created authentication section

4 files changed, 84 insertions, 6 deletions

diff --git a/server/sonar-docs/src/pages/instance-administration/authentication/bitbucket-cloud.md b/server/sonar-docs/src/pages/instance-administration/authentication/bitbucket-cloud.md
new file mode 100644
index 00000000000..a79d8314114
--- /dev/null
+++ b/server/sonar-docs/src/pages/instance-administration/authentication/bitbucket-cloud.md
@@ -0,0 +1,23 @@
+---
+title: Bitbucket Cloud
+url: /instance-administration/authentication/bitbucket-cloud/
+---
+
+To allow users to log in with Bitbucket Cloud credentials, you need to use an [OAuth consumer](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/) and set the authentication settings in SonarQube. See the following sections for more on setting up authentication.
+
+## Setting your OAuth consumer settings
+Create your OAuth consumer in your Bitbucket Cloud workspace settings and specify the following:
+
+- **Name** – the name of your OAuth consumer.
+- **Callback URL** – your SonarQube instance URL.
+- **Permissions**: 
+	* **Account**: **Read** and **Email** access.
+	* **Workspace membership**: **Read** access.
+
+## Setting your authentication settings in SonarQube
+To set your global authentication settings, navigate to **Administration > Configuration > General Settings > Authentication > Bitbucket Cloud Authentication** and update the following settings:
+
+- **Enabled** - set to true.
+- **OAuth consumer key** - enter the **Key** from your OAuth consumer page in Bitbucket.
+- **OAuth consumer secret** - enter the **Secret** from your OAuth consumer page in Bitbucket.
+- **Workspaces** - Only users from Bitbucket Workspaces that you add here will be able to authenticate in SonarQube. This is optional, but _highly_ recommended to ensure only the users you want to log in with Bitbucket credentials are able to. 
diff --git a/server/sonar-docs/src/pages/instance-administration/authentication/github.md b/server/sonar-docs/src/pages/instance-administration/authentication/github.md
new file mode 100644
index 00000000000..f0987f3f954
--- /dev/null
+++ b/server/sonar-docs/src/pages/instance-administration/authentication/github.md
@@ -0,0 +1,22 @@
+---
+title: Github
+url: /instance-administration/authentication/github/
+---
+
+To allow users to log in with GitHub credentials, you must rely on a GitHub App. You can reuse one that you previously created although we highly recommend to create a dedicated one.
+
+## Creating a dedicated app for authentication
+If you want to use a dedicated app for GitHub authentication, you can create a GitHub OAuth app. You'll find general instructions for creating a GitHub OAuth App [here](https://docs.github.com/en/free-pro-team@latest/developers/apps/creating-an-oauth-app). Specify the following settings in your OAuth App:
+
+- **Homepage URL** – the public URL of your SonarQube server. For example, `https://sonarqube.mycompany.com`. For security reasons, HTTP is not supported, and you must use HTTPS. The public URL is configured in SonarQube at **[Administration > General > Server base URL](/#sonarqube-admin#/admin/settings)**.
+- **Authorization callback URL** – your instance's base URL. For example, `https://yourinstance.sonarqube.com`.
+
+## Setting your authentication settings in SonarQube
+
+Navigate to **Administration > Configuration > General Settings > Authentication > GitHub Authentication** and update the following:
+
+1. **Enabled** – set the switch to `true`.
+1. **Client ID** – the Client ID is found below the GitHub App ID on your GitHub App's page.
+1. **Client Secret** – the Client secret is found below the Client ID on your GitHub App's page.
+  
+Now, from the login page, your users can connect their GitHub accounts with the new "Log in with GitHub" button.
diff --git a/server/sonar-docs/src/pages/instance-administration/authentication/gitlab.md b/server/sonar-docs/src/pages/instance-administration/authentication/gitlab.md
new file mode 100644
index 00000000000..8661bde4e46
--- /dev/null
+++ b/server/sonar-docs/src/pages/instance-administration/authentication/gitlab.md
@@ -0,0 +1,39 @@
+---
+title: Gitlab
+url: /instance-administration/authentication/gitlab/
+---
+
+You can delegate authentication to GitLab using a dedicated GitLab OAuth application.
+
+## Creating a GitLab OAuth app
+You can find general instructions for creating a GitLab OAuth app [here](https://docs.gitlab.com/ee/integration/oauth_provider.html).
+
+Specify the following settings in your OAuth app:
+
+- **Name** – your app's name, such as SonarQube.
+- **Redirect URI** – enter your SonarQube URL with the path `/oauth2/callback/gitlab`. For example, `https://sonarqube.mycompany.com/oauth2/callback/gitlab`.
+- **Scopes** – select **api** if you plan to enable group synchronization. Select **read_user** if you only plan to delegate authentication.
+
+After saving your application, GitLab takes you to the app's page. Here you find your **Application ID** and **Secret**.
+
+## Setting your authentication settings in SonarQube
+Open your SonarQube instance, and navigate to **Administration > Configuration > General Settings > Authentication > GitLab Authentication**. Set the following settings to finish setting up GitLab authentication:
+
+- **Enabled** – set to `true`.
+- **Application ID** – the Application ID is found on your GitLab app's page.
+- **Secret** – the Secret is found on your GitLab app's page.
+
+On the login form, the new "Log in with GitLab" button allows users to connect with their GitLab accounts.
+
+## GitLab group synchronization
+Enable **Synchronize user groups** at **Administration > Configuration > General Settings > Authentication > GitLab Authentication** to associate GitLab groups with existing SonarQube groups of the same name. GitLab users inherit membership to subgroups from parent groups. 
+
+To synchronize a GitLab group or subgroup with a SonarQube group, name the SonarQube group with the full path of the GitLab group or subgroup URL. 
+
+For example, with the following GitLab group setup:
+
+- GitLab group = My Group
+- GitLab subgroup = My Subgroup
+- GitLab subgroup URL = `https://YourGitLabURL.com/my-group/my-subgroup`
+
+You should name your SonarQube group `my-group` to synchronize it with your GitLab group and `my-group/my-subgroup` to synchronize it with your GitLab subgroup.
diff --git a/server/sonar-docs/src/pages/instance-administration/authentication/overview.md b/server/sonar-docs/src/pages/instance-administration/authentication/overview.md
index 8a8b0bcbc2f..04474bc9e71 100644
--- a/server/sonar-docs/src/pages/instance-administration/authentication/overview.md
+++ b/server/sonar-docs/src/pages/instance-administration/authentication/overview.md
@@ -14,11 +14,5 @@ When using group mapping, the following caveats apply regardless of which delega
 [[warning]]
 |When group mapping is configured, the delegated authentication source becomes the only place to manage group membership, and the user's groups are re-fetched with each log in.
 
-## GitHub, GitLab, and Bitbucket Cloud Authentication
-You can delegate authentication to GitHub, GitLab, or Bitbucket Cloud. See the corresponding DevOps Platform integration page for more information:
-- [GitHub Enterprise and GitHub.com](/analysis/github-integration/)
-- [GitLab Self-Managed and GitLab.com](/analysis/gitlab-integration/)
-- [Bitbucket Cloud](/analysis/bitbucket-cloud-integration/)
-
 ## Revoking tokens for deactivated users
 When SonarQube authentication is delegated to an external identity provider, deactivating a user on the identity provider side does not remove any tokens associated with the user on the SonarQube side. We recommend deactivating the user in SonarQube at **Administration > Security > Users** by selecting **Deactivate** from the ![Settings drop-down](/images/gear.png) drop-down menu to ensure tokens associated with that user can no longer be used.