SONAR-16259 - Token Types Documentation

3 files changed, 35 insertions, 7 deletions

diff --git a/server/sonar-docs/src/pages/analysis/analysis-parameters.md b/server/sonar-docs/src/pages/analysis/analysis-parameters.md
index 6accf76362e..aeb7710e378 100644
--- a/server/sonar-docs/src/pages/analysis/analysis-parameters.md
+++ b/server/sonar-docs/src/pages/analysis/analysis-parameters.md
@@ -46,10 +46,10 @@ By default, user authentication is required to prevent anonymous users from brow
 
 When authentication is required or the "Anyone" pseudo-group does not have permission to perform analyses, you'll need to supply the credentials of a user with Execute Analysis permissions for the analysis to run under.
 
-Key | Description | Default
----|----|---
-`sonar.login` | The [authentication token](/user-guide/user-token/) or login of a SonarQube user with Execute Analysis permission on the project. |
-`sonar.password` | If you're using an authentication token, leave this blank. If you're using a login, this is the password that goes with your `sonar.login` username. |
+Key | Description                                                                                                                                                                                   | Default
+---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---
+`sonar.login` | The [authentication token](/user-guide/user-token/) or login of a SonarQube user with either Execute Analysis permission on the project or Global Execute Analysis permission. |
+`sonar.password` | If you're using an authentication token, leave this blank. If you're using a login, this is the password that goes with your `sonar.login` username.                                          |
 
 ### Web Services
 Key | Description | Default
diff --git a/server/sonar-docs/src/pages/instance-administration/security.md b/server/sonar-docs/src/pages/instance-administration/security.md
index 4d14282d578..5bcb9fffe16 100644
--- a/server/sonar-docs/src/pages/instance-administration/security.md
+++ b/server/sonar-docs/src/pages/instance-administration/security.md
@@ -82,7 +82,9 @@ When you create a user in SonarQube's own database, it is considered local and w
 
 Similarly, all non-local accounts will be authenticated only against the external tool. 
 
-An Administrator can manage tokens on a user's behalf via **[Administration > Security > Users](/#sonarqube-admin#/admin/users)**. From here, click in the user's **Tokens** column to see the user's existing tokens, and either revoke existing tokens or generate new ones. Once established, a token is the only credential needed to run an analysis. Tokens should be passed as the value of the `sonar.login` property.
+An Administrator can manage tokens on a user's behalf via **[Administration > Security > Users](/#sonarqube-admin#/admin/users)**. From here, click in the user's **Tokens** column to see the user's existing tokens, and either revoke existing tokens or generate new ones. 
+An Administrator can only create [user tokens](/user-guide/user-token/) on behalf of another user.
+Once established, a token is the only credential needed to run an analysis. Tokens should be passed as the value of the `sonar.login` property.
 
 ### Default Admin Credentials
 When installing SonarQube, a default user with Administer System permission is created automatically:
diff --git a/server/sonar-docs/src/pages/user-guide/user-token.md b/server/sonar-docs/src/pages/user-guide/user-token.md
index b3650a030dc..4debde8908e 100644
--- a/server/sonar-docs/src/pages/user-guide/user-token.md
+++ b/server/sonar-docs/src/pages/user-guide/user-token.md
@@ -5,11 +5,37 @@ url: /user-guide/user-token/
 
 Users can generate tokens that can be used to run analyses or invoke web services without access to the user's actual credentials.
 
+## Types of Tokens
+
+### User Tokens
+These tokens can be used to run analysis and to invoke web services, based on the token author's permissions.
+
+### Project Analysis Tokens
+These tokens can be used to run analysis on a specific project. 
+
+In order to create this type of token, the user should have Global Execute Analysis permission or Execute Analysis permission on the token's associated project.
+
+If the token's author loses Execute Analysis permissions for the associated project, the token will no longer be valid for performing an analysis.
+
+[[info]]
+| The usage of Project Analysis Tokens is encouraged for security reasons. 
+| If such a token were to leak, an attacker would only gain access to analyze a single project. Interacting with the web services would not be possible for them.
+
+
+### Global Analysis Tokens
+These tokens can be used to run analysis on every project.
+
+In order to create this type of tokens, the user should have Global Execute Analysis Permission.
+
+If the token's author loses the Global Execute Analysis permission, the token will no longer be valid for performing an analysis.
+
 ## Generating a token
 
 You can generate new tokens at **User > My Account > Security**.
 
-The form at the bottom of the page allows you to generate new tokens. Once you click the **Generate** button, you will see the token value. Copy it immediately; once you dismiss the notification you will not be able to retrieve it.
+The form at the top of the page allows you to generate new tokens, specifying their token type.
+
+Once you click the **Generate** button, you will see the token value. Copy it immediately; once you dismiss the notification you will not be able to retrieve it.
 
 ## Revoking a token
 
@@ -22,4 +48,4 @@ User tokens must replace your normal login process in the following scenarios:
 * when running analyses on your code: replace your login with the token in the `sonar.login` property. 
 * when invoking web services: just pass the token instead of your login while doing the basic authentication.
 
-In both cases, you don't need to provide a password (so when running analyses on your code, the property `sonar.password` is optional). Using a token is the preferred method over using a login and password.
\ No newline at end of file
+In both cases, you don't need to provide a password (so when running analyses on your code, the property `sonar.password` is optional). Using a token is the preferred method over using a login and password.