This documents describes a concept for a fine-grained permission managing via the SCMMv2 UI.
\nSCMMv1 's permissions are only related to Repositories:
\nAll other permissions are handled by distinguishing administrators from ordinary users.\nAdmins can do everything, users nothing except for their repository permissions.
\nSome more permission-related features are added by plugins:
\nSCMMv2 introduces much more fine-grained permission checks under the hood.\nIn the code permissions for all kinds of operations are designed as follows:
\nsubject:verb:item,configuration:read:gitrepository:write:42,In addition, there are permissions that do not relate to an item, which are called \"global permissions\", for example\nconfiguration:list.
The challenge solved by this document is to provide a concept that allows SCMMv2 users to manage these permissions.\nThat is, to assign those permissions to users and groups via the UI or REST API.
\nThis is not a core part of the concept but might be interesting when implementing it.
\nSCMM uses the Apache Shiro security framework that allows for assigning permission strings (such as subject:verb:item)\nto users. These can also contain wildcards (*). For example
* realizes the administrator,user:read:* means reading is allowed on all users,user:*:arthur means all operations are allowed on a specific user.Then the application can check if a user has a permission.\nFor example:
\n*user:read:*? Yes!In order to get a little more type safe, SCM-Manager uses the\nShiro-static-permissions (ssp) library that scans the classpath for\nannotations such as the following
\n @StaticPermissions(\n value = \"user\",\n globalPermissions = {\"create\", \"list\", \"autocomplete\"},\n permissions = {\"read\", \"modify\", \"delete\", \"changePassword\"})and creates *Permissions classes that contain methods for checking each permission, for example like so
UserPermissions.read().check(id);When a user logs in, all different kinds of permissions (* if admin, permissions for repositories,\nfrom groups, some additional technical permissions such as autocomplete, etc.) are collected and added to the Shiro\nsubject in the DefaultAuthorizationCollector class.
Here are some more examples of permissions existing in SCMMv2 core, at the time of writing.\nLook for @StaticPermissions and note that there the annotation also declares defaults for permissions and globalPermissions.
In order to fulfill the requirements, this concept describes
\nThe global permission component can be reached from either user and groups components navigations. The following mockup\nshows this in the user component:
\nThe UI
\nThe repository permission are already implemented and can be reached via Repositories | Permissions. Right now, it\nallows for assigning the roles READ, WRITE, OWNER as in SCMMv1 (see above). Internally they are mapped to shiro\npermissions (see PermissionType).
The UI is extended like so:
\nAdvanced button per user or group entry opens a modal dialogNote that the examples here are not specified in HAL/HATEOAS for brevity.
\nAssigning global permissions must be implemented for either user and groups!\nBoth use the same available permissions.
\nThe following shows user as an example.
\n/globalPermissions{\n \"permissions\": [\n \"configuration:read:git\",\n \"configuration:write:git\",\n \"configuration:read\",\n \"configuration:write\",\n \"plugin:read\",\n \"plugin:write\",\n \"group:read\",\n \"user:read\",\n \"repository:read\"\n ]\n}/users/{id}/permissions/{\n \"permissions\": [\n \"configuration:read:git\",\n \"configuration:write:git\",\n \"configuration:read\",\n \"configuration:write\",\n \"plugin:read\",\n \"plugin:write\",\n \"group:read\",\n \"user:read\",\n \"repository:read\"\n ]\n}/repositoryPermissions (similar to /repositoryTypes){\n \"roles\": [\n {\n \"name\": \"Reader\",\n \"verbs\": [ \"read\", \"pull\" ]\n },\n {\n \"name\": \"Owner\",\n \"verbs\": [ \"*\" ]\n }\n ],\n \"verbs\": [ \"read\", \"pull\", \"push\", \"..\", \"*\" ]\n}Already implemented in PermissionRootResource. Needs to be adpated from roles (WRITE) to shiro permissions\n(repository:read:42).
/repositories/{namespace}/{name}/permissions{\n \"permissions\": [\n {\n \"name\": \"trillian\",\n \"permissions\": [ \"read\", \"pull\" ],\n \"groupPermission\": false\n },\n {\n \"name\": \"owners\",\n \"permissions\": [ \"*\" ],\n \"groupPermission\": true\n }\n ]\n}This example shows the user trillian having the READER role and the group owners having the OWNER role.\nNote that
* permission also implies all new permissions (e.g. defined by plugins or added in future versions)and therefore has different semantics as listing all currently available permissions.
\nrepositories:<verb stored via REST API>:<ID of the repository identified by namespace and name>./repositories/{namespace}/{name}/permissions/trillian) that can be\nused for updating permissions via PUT requests.permissions does not contain :!The biggest technical challenges for this concept are the questions:
\nWhere each questions needs to be answered for
\npermissions.
\nIn order to implement this for global permissions an existing mechanism of SCM-Manager can be used:\nThe SecuritySystem, implemented by the DefaultSecuritySystem.
The DefaultSecuritySystem reads all permissions.xml files from classpath, which also works for plugins (see\nProof Of Concept).
These can be queried using securitySystem.getAvailablePermissions().
For SCMMv2 we could extend this mechanism by
\npermissions.xml to contain only <permission><value>, because <display-name> and <description>\nneed to be internationalized, see i18n.ssp library to generate permissions.xml files from @StaticPermissions annotations.\nThe annotations should be extended to support a list of permissions that are not written to permissions.xml\n(e.g. user:autocomplete)The SecuritySystem also provides means to assign, store and load permissions to users or groups using Shiro string\npermissions like so:
AssignedPermission groupPermission = new AssignedPermission(\"configurers\", true,\"configuration:*\");\nsecuritySystem.addPermission(groupPermission);\nAssignedPermission userPermission = new AssignedPermission(\"arthur\", \"group:*\");\nsecuritySystem.addPermission(userPermission);\nlog.info(\"All permissions: {}\", securitySystem.getAllPermissions()); // Contains the permissions just addedSee also the Proof Of Concept.
\nThe evaluation of permissions assigned via the SecuritySystem is already implemented in the\nDefaultAuthorizationCollector.
Adding items (e.g. new users) dynamically during runtime is not implemented by the SecuritySystem and in order to\nkeep this simple we do not plan to support it, yet. See considered alternatives.
For repository permissions we need to implement a new mechanism for discovering available permissions .\nAssigning is already implemented (on role level, e.g. WRITE), which needs to be adapted to shiro permission level\n(e.g. repository:read:42).
We need to implement a new mechanism for discovering available permssions. Let's call it RepositoryPermissionResolver.\nIt can work similar to the DefaultSecuritySystem (see global permissions). It reads all repository-permissions.xml\nfiles from classpath, which makes it extensible for plugins.
This obsoletes the PermissionType enum.
<permissions>\n \n <permission>read</permission>\n <permission>write</permission>\n \n <role>\n <name>WRITER</name>\n <permission>read</permission>\n <permission>pull</permission>\n <permission>push</permission>\n </role>\n</permissions> This is already implemented in RepositoryManagers. Needs to be adapted from roles (WRITE) to shiro permissions\n(repository:read:42).
Same here: Already implemented in DefaultAuthorizationCollector. Needs to be adapted from roles to shiro permissions.
In addition to the fine-grained permission management described in this concept, we could just keep the admin flag\n(or role) that add the permission * to a user.\nIt's already implemented and a well-known concept from SCMMv1.
Once permissions can be managed, an additional permission is necessary that answers the question: Who is allowed to\nmanage permissions?
\nThis permission has to be checked before permissions are read or written. It should be implemented in the\nDefaultSecuritySystem, instead of the assertIsAdmin() method.
For now, it is sufficiently to create a Permission permission (using @StaticPermissions) with global verbs read\nand write. That is,
permission:readpermission:writeInternationalization can be handled using the following conventions:
\nplugins.json (also for core), see i18n for Pluginspermissions.<shiro-String>, containing displayName and description each.Example:
\n{\n \"permissions\": {\n \"repository:read\": {\n \"displayName\": \"All Repositories (read)\",\n \"description\": \"Read access to all repositories\"\n }\n }\n}One shortcoming of limiting the global permission concept to verbs (not items) is that the functionality of the\nscm-groupmanager-plugin is not included.\nThat is, we need to migrate our implement it for SCMMv2. Most likely it's less effort to implement a new plugin,\nbecause we need a new SCMMv2 UI and can use the SecuritySystemto set thegroup:*:
The following needs to be implemented:
\ngroup:manage permission (permission.xml) including i18n in\nplugins.json.GroupPermissions (generated via ssp),\nbut via SecurityUtils.getSubject().checkPermission(permission);SecuritySystem to set the group:*:<id> permissions.This chapter documents some other approaches that were considered but rejected and the reasons for rejecting them.
\nsubject:verb:item level, why not allow our users to make use of it?item part. This suffices most use cases.subject:verb:item level, why not allow our users to make use of it?This chapter documents the permissions implemented in SCM-Manager core and a lot of plugins that can be assigned to users and groups\nusing the GUI/API.\nBe aware, that this is only a snapshot and may not track each change in a plugin or the core. To get the concrete list of permissions\nfor a concrete version of the core or a plugin, take a look at the corresponding permissions.xml, repository-permissions.xml and\nplugins.json files.
| plugin | \npermission | \ndescription | \n
|---|---|---|
| core | \nrepository:read,pull:* | \nread all repositories | \n
| core | \nrepository:read,pull,push:* | \nwrite all repositories | \n
| core | \nrepository:* | \nown all repositories | \n
| core | \nrepository:create | \nCreate repositories | \n
| core | \nuser:* | \nadminister users | \n
| core | \ngroup:* | \nadminister groups | \n
| core | \nconfiguration:list | \nbasic permission for all configuration permissions; needed to see config menu item | \n
| core | \nconfiguration:read,write:global | \nadminister core configuration | \n
| core | \nconfiguration:read,write:* | \nadminister overall configuration (including all plugins) | \n
| git | \nconfiguration:read,write:git | \nadminister global git settings | \n
| git | \nrepository:git:* | \nadminister repository specific git settings | \n
| hg | \nconfiguration:read,write:hg | \nadminister global mercurial settings | \n
| hg | \nrepository:hg:* | \nadminister repository specific mercurial settings | \n
| svn | \nconfiguration:read,write:svn | \nadminister global subversion settings | \n
| svn | \nrepository:svn:* | \nadminister repository specific subversion settings | \n
| authormapping | \nrepository:authormapping:* | \nread and modify author mappings for all repositories | \n
| auth-ldap | \nconfiguration:read,write:ldap | \nadminister ldap server | \n
| cas | \nconfiguration:read,write:cas | \nadminister cas server | \n
| statistic | \nrepository:computeStatistics:* | \nrecompute statistics for all repositories | \n
| jenkins | \nconfiguration:read,write:jenkins | \nadminister global jenkins server | \n
| jenkins | \nrepository:jenkins:* | \nadminister repository specific jenkins servers | \n
| jira | \nconfiguration:read,write:jira | \nadminister global jira server | \n
| jira | \nrepository:jira:* | \nadminister repository specific jira servers | \n
| pathwp | \nrepository:pathwp:* | \nadminister write protected paths for all repositories | \n
| branchwp | \nrepository:branchwp:* | \nadminister write protected paths for all repositories | \n
| tagprotection | \nconfiguration:read,write:tagprotection | \nadminister globally protected tags | \n
| script | \nscript:read,modify,execute | \nread, modify and execute scripts | \n
| webhook | \nconfiguration:read,write:webhook | \nadminister web hooks | \n
| webhook | \nrepository:webhook:* | \nadminister web hooks for all repositories | \n
| redmine | \nconfiguration:read,write:redmine | \nadminister global redmine server | \n
| redmine | \nrepository:redmine:* | \nadminister repository specific redmine servers | \n
| notify | \nrepository:notify:* | \nadminister notify settings for all repositories | \n
| support | \nsupport:information | \nread support relevant information | \n
| support | \nsupport:information,logging | \nread support relevant information and enable trace log | \n
configuration:read,write:mail | \nadminister mail server | \n|
| groupmanager | \ngroup:manage:* | \nassign group managers | \n
| ssh | \nuser:readAuthorizedKeys:* | \nread authorization keys for all users | \n
| ssh | \nuser:readAuthorizedKeys,writeAuthorizedKeys:* | \nconfigure authorization keys for all users | \n
| plugin | \nverb | \ndescription | \n
|---|---|---|
| core | \nread | \nread metadata of repository | \n
| core | \nmodify | \nmodify metadata of repository | \n
| core | \ndelete | \ndelete repository | \n
| core | \npull | \npull/checkout repository | \n
| core | \npush | \npush/commit to repository | \n
| core | \npermissionRead | \nread permissions of repository | \n
| core | \npermissionWrite | \nmodify permissions for repository | \n
| core | \n* | \nchange everything for repository (\"owner\") | \n
| git | \ngit | \nadminister git settings for repository | \n
| hg | \nhg | \nadminister mercurial settings for repository | \n
| svn | \nsvn | \nadminister subversion settings for repository | \n
| review | \ncreatePullRequest | \ncreate pull requests | \n
| review | \nreadPullRequest | \nread pull requests | \n
| review | \ncommentPullRequest | \nwrite comments in pull requests and delete/edit own comments | \n
| review | \nmodifyPullRequest | \nedit/delete pull requests and comments | \n
| review | \nmergePullRequest | \nmerge/reject pull requests | \n
| authormapping | \nauthormapping | \nmodify author mappings | \n
| jenkins | \njenkins | \nadminister jenkins server for repository | \n
| jira | \njira | \nadminister jira server for repository | \n
| pathwp | \npathwp | \nadminister write protected paths for repository | \n
| redmine | \nredmine | \nadminister redmine server for repository | \n
| notify | \nnotify | \nadminister notify settings for repository | \n
| branchwp | \nbranchwp | \nadminister write protected paths for repository | \n
| webhook | \nwebhook | \nadminister web hools for repository | \n
The verbs for roles are merged internally, so that a resulting role will have all verbs specified by any plugin.\nMind that a OWNER has overall permissions, including all possible permissions for all plugins.
| plugin | \nrole | \nverbs | \n
|---|---|---|
| core | \nREAD | \nread, pull | \n
| core | \nWRITE | \nread, pull, push | \n
| core | \nOWNER | \n* | \n
| review | \nREAD | \nreadPullRequest | \n
| review | \nWRITE | \ncreatePullRequest, readPullRequest, commentPullRequest, mergePullRequest | \n
| statistic | \nREAD | \nreadStatistics | \n