# HG changeset patch
# User Marcin Kuzminski <marcin@rhodecode.com>
# Date 2020-07-07 11:04:19
# Node ID d880ce51d0dac486130b5bb9d1c020010ebf048f
# Parent  d44504983605200ccc7d1e064772c2138cf2e6c6

auth-tokens: expose all roles with explanation to help users understand it better.

diff --git a/rhodecode/lib/helpers.py b/rhodecode/lib/helpers.py
--- a/rhodecode/lib/helpers.py
+++ b/rhodecode/lib/helpers.py
@@ -89,7 +89,7 @@ from rhodecode.lib.vcs.backends.base imp
 from rhodecode.lib.index.search_utils import get_matching_line_offsets
 from rhodecode.config.conf import DATE_FORMAT, DATETIME_FORMAT
 from rhodecode.model.changeset_status import ChangesetStatusModel
-from rhodecode.model.db import Permission, User, Repository
+from rhodecode.model.db import Permission, User, Repository, UserApiKeys
 from rhodecode.model.repo_group import RepoGroupModel
 from rhodecode.model.settings import IssueTrackerSettingsModel
 
diff --git a/rhodecode/model/db.py b/rhodecode/model/db.py
--- a/rhodecode/model/db.py
+++ b/rhodecode/model/db.py
@@ -1133,14 +1133,16 @@ class UserApiKeys(Base, BaseModel):
 
     # ApiKey role
     ROLE_ALL = 'token_role_all'
-    ROLE_HTTP = 'token_role_http'
     ROLE_VCS = 'token_role_vcs'
     ROLE_API = 'token_role_api'
+    ROLE_HTTP = 'token_role_http'
     ROLE_FEED = 'token_role_feed'
     ROLE_ARTIFACT_DOWNLOAD = 'role_artifact_download'
+    # The last one is ignored in the list as we only
+    # use it for one action, and cannot be created by users
     ROLE_PASSWORD_RESET = 'token_password_reset'
 
-    ROLES = [ROLE_ALL, ROLE_HTTP, ROLE_VCS, ROLE_API, ROLE_FEED, ROLE_ARTIFACT_DOWNLOAD]
+    ROLES = [ROLE_ALL, ROLE_VCS, ROLE_API, ROLE_HTTP, ROLE_FEED, ROLE_ARTIFACT_DOWNLOAD]
 
     user_api_key_id = Column("user_api_key_id", Integer(), nullable=False, unique=True, default=None, primary_key=True)
     user_id = Column("user_id", Integer(), ForeignKey('users.user_id'), nullable=True, unique=None, default=None)
@@ -1205,6 +1207,22 @@ class UserApiKeys(Base, BaseModel):
             cls.ROLE_ARTIFACT_DOWNLOAD: _('artifacts downloads'),
         }.get(role, role)
 
+    @classmethod
+    def _get_role_description(cls, role):
+        return {
+            cls.ROLE_ALL: _('Token for all actions.'),
+            cls.ROLE_HTTP: _('Token to access RhodeCode pages via web interface without '
+                             'login using `api_access_controllers_whitelist` functionality.'),
+            cls.ROLE_VCS: _('Token to interact over git/hg/svn protocols. '
+                            'Requires auth_token authentication plugin to be active. <br/>'
+                            'Such Token should be used then instead of a password to '
+                            'interact with a repository, and additionally can be '
+                            'limited to single repository using repo scope.'),
+            cls.ROLE_API: _('Token limited to api calls.'),
+            cls.ROLE_FEED: _('Token to read RSS/ATOM feed.'),
+            cls.ROLE_ARTIFACT_DOWNLOAD: _('Token for artifacts downloads.'),
+        }.get(role, role)
+
     @property
     def role_humanized(self):
         return self._get_role_name(self.role)
@@ -3783,7 +3801,7 @@ class ChangesetComment(Base, BaseModel):
     def get_index_from_version(cls, pr_version, versions):
         num_versions = [x.pull_request_version_id for x in versions]
         try:
-            return num_versions.index(pr_version) +1
+            return num_versions.index(pr_version) + 1
         except (IndexError, ValueError):
             return
 
diff --git a/rhodecode/templates/admin/my_account/my_account_auth_tokens.mako b/rhodecode/templates/admin/my_account/my_account_auth_tokens.mako
--- a/rhodecode/templates/admin/my_account/my_account_auth_tokens.mako
+++ b/rhodecode/templates/admin/my_account/my_account_auth_tokens.mako
@@ -11,9 +11,15 @@
     <div class="panel-body">
     <div class="apikeys_wrap">
       <p>
-         ${_('Authentication tokens can be used to interact with the API, or VCS-over-http. '
-         'Each token can have a role. Token with a role can be used only in given context, '
-         'e.g. VCS tokens can be used together with the authtoken auth plugin for git/hg/svn operations only.')}
+         ${_('Available roles')}:
+        <ul>
+         % for role in h.UserApiKeys.ROLES:
+             <li>
+                 <span class="tag disabled">${h.UserApiKeys._get_role_name(role)}</span>
+                 <span>${h.UserApiKeys._get_role_description(role) |n}</span>
+             </li>
+         % endfor
+        </ul>
       </p>
       <table class="rctable auth_tokens">
         <tr>
@@ -36,7 +42,7 @@
                 </td>
                 <td class="td-wrap">${auth_token.description}</td>
                 <td class="td-tags">
-                    <span class="tag disabled">${auth_token.role_humanized}</span>
+                    <span class="tooltip tag disabled" title="${h.UserApiKeys._get_role_description(auth_token.role)}">${auth_token.role_humanized}</span>
                 </td>
                 <td class="td">${auth_token.scope_humanized}</td>
                 <td class="td-exp">
diff --git a/rhodecode/templates/admin/users/user_edit_auth_tokens.mako b/rhodecode/templates/admin/users/user_edit_auth_tokens.mako
--- a/rhodecode/templates/admin/users/user_edit_auth_tokens.mako
+++ b/rhodecode/templates/admin/users/user_edit_auth_tokens.mako
@@ -16,9 +16,15 @@
     <div class="panel-body">
         <div class="apikeys_wrap">
           <p>
-             ${_('Authentication tokens can be used to interact with the API, or VCS-over-http. '
-             'Each token can have a role. Token with a role can be used only in given context, '
-             'e.g. VCS tokens can be used together with the authtoken auth plugin for git/hg/svn operations only.')}
+             ${_('Available roles')}:
+            <ul>
+             % for role in h.UserApiKeys.ROLES:
+                 <li>
+                     <span class="tag disabled">${h.UserApiKeys._get_role_name(role)}</span>
+                     <span>${h.UserApiKeys._get_role_description(role) |n}</span>
+                 </li>
+             % endfor
+            </ul>
           </p>
           <table class="rctable auth_tokens">
             <tr>
@@ -41,7 +47,7 @@
                     </td>
                     <td class="td-wrap">${auth_token.description}</td>
                     <td class="td-tags">
-                        <span class="tag disabled">${auth_token.role_humanized}</span>
+                        <span class="tooltip tag disabled" title="${h.UserApiKeys._get_role_description(auth_token.role)}">${auth_token.role_humanized}</span>
                     </td>
                     <td class="td">${auth_token.scope_humanized}</td>
                     <td class="td-exp">