SONAR-15326 Document the encryption of DevOps platform secrets

6 files changed, 18 insertions, 12 deletions

diff --git a/server/sonar-docs/src/pages/analysis/azuredevops-integration.md b/server/sonar-docs/src/pages/analysis/azuredevops-integration.md
index 540e074e670..62b1528d00c 100644
--- a/server/sonar-docs/src/pages/analysis/azuredevops-integration.md
+++ b/server/sonar-docs/src/pages/analysis/azuredevops-integration.md
@@ -29,7 +29,9 @@ To import your Azure DevOps repositories into SonarQube, you need to first set y
  
 - **Configuration Name** (Enterprise and Data Center Edition only) – The name used to identify your Azure DevOps configuration at the project level. Use something succinct and easily recognizable.
 - **Azure DevOps collection/organization URL** – If you are using Azure DevOps Server, provide your full Azure DevOps collection URL. For example, `https://ado.your-company.com/DefaultCollection`. If you are using Azure DevOps Services, provide your full Azure DevOps organization URL. For example, `https://dev.azure.com/your_organization`.
-- **Personal Access Token** – An Azure DevOps user account is used to decorate Pull Requests. We recommend using a dedicated Azure DevOps account with Administrator permissions. You need a [personal access token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=tfs-2017&tabs=preview-page) from this account with the scope authorized for **Code > Read & Write** for the repositories that will be analyzed. This personal access token is used for pull request decoration, and you'll be asked for another personal access token for importing projects in the following section.
+- **Personal Access Token** – An Azure DevOps user account is used to decorate Pull Requests. We recommend using a dedicated Azure DevOps account with Administrator permissions. You need a [personal access token](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=tfs-2017&tabs=preview-page) from this account with the scope authorized for **Code > Read & Write** for the repositories that will be analyzed. Administrators can encrypt this token at **Administration > Configuration > Encryption**. See the **Settings Encryption** section of the [Security](/instance-administration/security/) page for more information. 
+
+   This personal access token is used to report your Quality Gate status to your pull requests. You'll be asked for another personal access token for importing projects in the following section.
 
 ### Adding a personal access token for importing repositories
 After setting your global settings, you can add a project from Azure DevOps by clicking the **Add project** button in the upper-right corner of the **Projects** homepage and selecting  **Azure DevOps**.
diff --git a/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md b/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md
index 040e769be65..0225cd1e0c0 100644
--- a/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md
+++ b/server/sonar-docs/src/pages/analysis/bitbucket-cloud-integration.md
@@ -38,7 +38,7 @@ To set your global ALM Integration settings, navigate to **Administration > ALM
 - **Configuration Name** (Enterprise and Data Center Edition only) – The name used to identify your Bitbucket Cloud configuration at the project level. Use something succinct and easily recognizable.
 - **Workspace ID** – The workspace ID is part of your bitbucket cloud URL `https://bitbucket.org/{WORKSPACE-ID}/{repository-slug}`
 - **OAuth Key** – Bitbucket automatically creates an OAuth key when you create your OAuth consumer. You can find it in your Bitbucket Cloud workspace settings under **OAuth consumers**.
-- **OAuth Secret** – Bitbucket automatically creates an OAuth secret when you create your OAuth consumer. You can find it in your Bitbucket Cloud workspace settings under **OAuth consumers**.
+- **OAuth Secret** – Bitbucket automatically creates an OAuth secret when you create your OAuth consumer. You can find it in your Bitbucket Cloud workspace settings under **OAuth consumers**. Administrators can encrypt this secret at **Administration > Configuration > Encryption**. See the **Settings Encryption** section of the [Security](/instance-administration/security/) page for more information.
 
 ### Adding your Bitbucket username and an app password
 After setting your global settings, you can add a project from Bitbucket Cloud by clicking the **Add project** button in the upper-right corner of the **Projects** homepage and selecting **Bitbucket**.
diff --git a/server/sonar-docs/src/pages/analysis/bitbucket-integration.md b/server/sonar-docs/src/pages/analysis/bitbucket-integration.md
index 83b8c6fc29d..23d8ae9c45d 100644
--- a/server/sonar-docs/src/pages/analysis/bitbucket-integration.md
+++ b/server/sonar-docs/src/pages/analysis/bitbucket-integration.md
@@ -31,7 +31,9 @@ To set your global ALM Integration settings, navigate to **Administration > ALM
 
 - **Configuration Name** (Enterprise and Data Center Edition only) – The name used to identify your Bitbucket Server configuration at the project level. Use something succinct and easily recognizable.
 - **Bitbucket Server URL** – your instances URL. For example, `https://bitbucket-server.your-company.com`.
-- **Personal Access Token** – A Bitbucket Server user account is used to decorate Pull Requests. We recommend using a dedicated Bitbucket Server account with Administrator permissions. You need a [Personal Access Token](https://confluence.atlassian.com/bitbucketserver0515/personal-access-tokens-961275199.html) from this account with **Read** permission for the repositories that will be analyzed. This personal access token is used for pull request decoration, and you'll be asked for another personal access token for importing projects in the following section.
+- **Personal Access Token** – A Bitbucket Server user account is used to decorate Pull Requests. We recommend using a dedicated Bitbucket Server account with Administrator permissions. You need a [Personal Access Token](https://confluence.atlassian.com/bitbucketserver0515/personal-access-tokens-961275199.html) from this account with **Read** permission for the repositories that will be analyzed. Administrators can encrypt this token at **Administration > Configuration > Encryption**. See the **Settings Encryption** section of the [Security](/instance-administration/security/) page for more information. 
+
+   This personal access token is used to report your Quality Gate status to your pull requests. You'll be asked for another personal access token for importing projects in the following section.
 
 ### Adding a personal access token for importing repositories
 After setting your global settings, you can add a project from Bitbucket Server by clicking the **Add project** button in the upper-right corner of the **Projects** homepage and selecting **Bitbucket**.
diff --git a/server/sonar-docs/src/pages/analysis/github-integration.md b/server/sonar-docs/src/pages/analysis/github-integration.md
index 265e3980aa7..b8ce1afc5ab 100644
--- a/server/sonar-docs/src/pages/analysis/github-integration.md
+++ b/server/sonar-docs/src/pages/analysis/github-integration.md
@@ -85,8 +85,8 @@ Navigate to **Administration > Configuration > General Settings > ALM Integratio
 - **GitHub URL** – For example, `https://github.company.com/api/v3` for GitHub Enterprise or `https://api.github.com/` for GitHub.com.
 - **GitHub App ID** – The App ID is found on your GitHub App's page on GitHub at **Settings > Developer Settings > GitHub Apps**. 
 - **Client ID** – The Client ID is found on your GitHub App's page.
-- **Client secret** – The Client secret is found on your GitHub App's page.
-- **Private Key** – Your GitHub App's private key. You can generate a `.pem` file from your GitHub App's page under **Private keys**. Copy and paste the whole contents of the file here.
+- **Client secret** – The Client secret is found on your GitHub App's page. Administrators can encrypt this secret at **Administration > Configuration > Encryption**. See the **Settings Encryption** section of the [Security](/instance-administration/security/) page for more information.
+- **Private Key** – Your GitHub App's private key. You can generate a `.pem` file from your GitHub App's page under **Private keys**. Copy and paste the whole contents of the file here. Administrators can encrypt this key at **Administration > Configuration > Encryption**. See the **Settings Encryption** section of the [Security](/instance-administration/security/) page for more information.
 
 ## Analyzing projects with GitHub Actions
 SonarScanners running in GitHub Actions can automatically detect branches and pull requests being built so you don't need to specifically pass them as parameters to the scanner.
diff --git a/server/sonar-docs/src/pages/analysis/gitlab-integration.md b/server/sonar-docs/src/pages/analysis/gitlab-integration.md
index 93646f1bc41..a318bf1ad6f 100644
--- a/server/sonar-docs/src/pages/analysis/gitlab-integration.md
+++ b/server/sonar-docs/src/pages/analysis/gitlab-integration.md
@@ -64,7 +64,9 @@ To import your GitLab projects into SonarQube, you need to first set your global
  
 - **Configuration Name** (Enterprise and Data Center Edition only) – The name used to identify your GitLab configuration at the project level. Use something succinct and easily recognizable.
 - **GitLab URL** – The GitLab API URL.
-- **Personal Access Token** – A GitLab user account is used to decorate Merge Requests. We recommend using a dedicated GitLab account with at least **Reporter** [permissions](https://docs.gitlab.com/ee/user/permissions.html) (the account needs permission to leave comments). You need a personal access token from this account with the scope authorized for **api** for the repositories that will be analyzed. This personal access token is used to merge request decoration. You'll be asked for another personal access token for importing projects in the following section. 
+- **Personal Access Token** – A GitLab user account is used to decorate Merge Requests. We recommend using a dedicated GitLab account with at least **Reporter** [permissions](https://docs.gitlab.com/ee/user/permissions.html) (the account needs permission to leave comments). Use a personal access token from this account with the **api** scope authorized for the repositories you're analyzing. Administrators can encrypt this token at **Administration > Configuration > Encryption**. See the **Settings Encryption** section of the [Security](/instance-administration/security/) page for more information.
+
+   This personal access token is used to report your Quality Gate status to your pull requests. You'll be asked for another personal access token for importing projects in the following section. 
 
 ### Adding a personal access token for importing projects
 After setting these global settings, you can add a project from GitLab by clicking the **Add project** button in the upper-right corner of the **Projects** homepage and selecting **GitLab**.
diff --git a/server/sonar-docs/src/pages/instance-administration/security.md b/server/sonar-docs/src/pages/instance-administration/security.md
index d27803c5591..b500b71a1ef 100644
--- a/server/sonar-docs/src/pages/instance-administration/security.md
+++ b/server/sonar-docs/src/pages/instance-administration/security.md
@@ -193,9 +193,9 @@ A unique secret key must be shared between all parts of the SonarQube infrastruc
 Go back to **[Administration > Configuration > Encryption](/#sonarqube-admin#/admin/settings/encryption)** and use the form that has been added to the interface to generated encrypted versions of your values.
 ![Encrypt values through the admin interface](/images/encrypt-value.png)
 1. **Use the encrypted values in your SonarQube server configuration**  
-Simply copy these encrypted values into _$SONARQUBE-HOME/conf/sonar.properties_
-```
-sonar.jdbc.password={aes-gcm}CCGCFg4Xpm6r+PiJb1Swfg==  # Encrypted DB password
-...
-sonar.secretKeyPath=C:/path/to/my/secure/location/my_secret_key.txt
-```
+Encrypted values can either be set in SonarQube or copied into _$SONARQUBE-HOME/conf/sonar.properties_:
+   ```
+   sonar.jdbc.password={aes-gcm}CCGCFg4Xpm6r+PiJb1Swfg==  # Encrypted DB password
+   ...
+   sonar.secretKeyPath=C:/path/to/my/secure/location/my_secret_key.txt
+   ```