Project

General

Profile

CdmAuthorisationAndAccessControl » History » Version 58

Andreas Kohlbecker, 12/21/2017 11:05 AM

1 56 Andreas Kohlbecker
# CDM authorisation and access control
2 2 Andreas Kohlbecker
3
It is evident that the cdm library needs authorisation and access control. There are library methods which need to protected from unauthorised execution and there is also the data which is exposed by the library. Not all data should be visible to every user so a [[HibernateSpringAndRowlevelSecurity|row level access control]] is needed.
4
5 57 Andreas Kohlbecker
Further information can be found in:
6
7
* [[WorkshopRightsAndRoles2017-11| Workshop Rights & Roles 2017-11]]
8
9 2 Andreas Kohlbecker
10 4 Andreas Kohlbecker
_This page only is a brief note for now, compiled by a lot of copy paste from the java doc!_
11 52 Andreas Kohlbecker
12 56 Andreas Kohlbecker
{{>toc}}
13 18 Andreas Kohlbecker
14 12 Andreas Kohlbecker
### Roles and CdmAuthorities
15 19 Andreas Kohlbecker
16
#### Roles
17 20 Andreas Kohlbecker
18 52 Andreas Kohlbecker
Roles are defined in two places:
19 19 Andreas Kohlbecker
20 52 Andreas Kohlbecker
1. eu.etaxonomy.cdm.persistence.hibernate.permission.Role
21
  * ROLE_ADMIN
22
  * ROLE_PROJECT_MANAGER
23
  * ROLE_USER_MANAGER
24
  * ROLE_PUBLISH
25 1 Andreas Kohlbecker
1. eu.etaxonomy.cdm.remote.config.MultiWebSecurityConfiguration
26 54 Andreas Kohlbecker
 * ROLE_MANAGE_CLIENT: see [Web service access control](#Web-service-access-control)
27 20 Andreas Kohlbecker
28
#### CdmAuthority
29
30 21 Andreas Kohlbecker
A `CdmAuthority` consists basically of two parts which are separated by a dot character '.'.
31 20 Andreas Kohlbecker
32 21 Andreas Kohlbecker
* permissionClass: an `CdmPermissionClass` instance with represents a cdm type or a part of the cdm type hierarchy. The className is always represented as an upper case string.
33
* property: The `CdmAuthority` only applies to instances which satisfy the specified property. Interpretation is up to type specific voters.
34
* operation: a string which specifies a `Operation` on that set of cdm types
35 1 Andreas Kohlbecker
* targetUuid: The operation may be restricted to a specific cdm entity by adding the entity uuid to the operation. The uuid string is enclosed in curly brackets '{' , '}' and appended to the end of the operation.
36 20 Andreas Kohlbecker
37
Examples for permissionStrings:
38
39
~~~
40 41 Andreas Kohlbecker
 TAXONBASE.[CREATE]
41
 TAXONBASE.[READ]
42
 TAXONBASE.[UPDATE]
43
 TAXONBASE.[DELETE]
44
 TAXONBASE.[DELETE,CREATE,UPDATE,READ]
45
 DESCRIPTIONBASE.UPDATE]
46
 DESCRIPTIONELEMENTBASE(Ecology).UPDATE]
47 1 Andreas Kohlbecker
 TAXONNODE.UPDATE{20c8f083-5870-4cbd-bf56-c5b2b98ab6a7}
48
~~~
49 21 Andreas Kohlbecker
50 24 Andreas Kohlbecker
in contrast to CdmAuthorities there are more general role like the following listed below, all these roles are having the  role prefix `'ROLE_'` which is defined in the String Security RoleVoter class:
51
52
~~~
53
 ROLE_ADMIN
54
 ROLE_USER_MANAGER
55
~~~
56
57 43 Andreas Kohlbecker
### Permission Groups
58
59
Permission groups can usually created as needed. The group name should reflect semantics the nature of the permission group.
60
61
The cdm provides default permission groups which are created by the `FirstDataInserter` in case they do not yet exist. See #4082 (implement default permission groups) for implementation details. Currently the following default permission groups exist: 
62
63 45 Andreas Kohlbecker
1. *Editor*: Contains all Authorities which are required to be granted for general editing, except the Authority for a specific taxonomical group. In order to actually enable an Editor to edit something it must be associated with a TAXONNODE Authority, e.g: @TAXONNODE.[CREATE,UPDATE,DELETE,READ]{...@}. Users which belong to this permission group are prohibited from toggling the publish-flag and from changing or deleting references and authors, but are able to create new ones. Once a 'Editor' has created a new Reference or Author the new entity is considered being still in the process of being created for some time even if the entity has already been saved to the database. See #4305 (newly created entities must stay editable even if a user only has the permission to create them) for implementation details on this feature.
64 43 Andreas Kohlbecker
65
~~~
66
REFERENCE.[CREATE,READ]
67
TAXONNAMEBASE.[CREATE,READ,UPDATE]
68
TEAMORPERSONBASE.[CREATE,READ]
69
TAXONBASE.[CREATE,UPDATE,DELETE,READ]
70
DESCRIPTIONBASE.[CREATE,UPDATE,DELETE,READ]
71
DESCRIPTIONELEMENTBASE.[CREATE,UPDATE,DELETE,READ]
72
~~~
73 44 Andreas Kohlbecker
1. *ProjectManager*: A permission group which enables a User to edit and delete entities which are of central importance for a whole project. Users which belong to this permission group are granted to edit and delete taxa, names, references, authors, terms and can toggle the publish-flag on taxa, speciemens and occurrences.
74 43 Andreas Kohlbecker
75
~~~
76
REFERENCE.[UPDATE,DELETE]
77
TAXONNAMEBASE.[DELETE]
78
TEAMORPERSONBASE.[UPDATE,DELETE]
79
ROLE_PROJECT_MANAGER
80
~~~
81
82 21 Andreas Kohlbecker
### Authorisation control
83
84
Different approaches of authorisation control need to be used in order to implement all kinds of CRUD permissions:
85
86
* service layer: method `@PreAuthorize` annotations with Spring EL, e.g. UserService:
87
88
~~~
89 1 Andreas Kohlbecker
@PreAuthorize("#username == authentication.name or hasRole('ROLE_ADMIN')")
90 21 Andreas Kohlbecker
public void changePasswordForUser(String username, String newPassword) {
91 1 Andreas Kohlbecker
...
92 21 Andreas Kohlbecker
~~~
93
* UPDATE and CREATE of cdm instances is protected by a Hibernate interceptor, the `CdmSecurityHibernateInterceptor@. This interceptor implements the  @onSave()` and `onFlushDirty` methods and thus can control creation and updating of cdm objects. Hibernate calls these methods for any entity which needs to be persisted even if a save or update operations causes a cascading save of objects connected to the object graph which is being saved. **TODO** implement DELETE (#3079)
94
* READ permissions can not be implemented using the `CdmSecurityHibernateInterceptor@. Reasons: @onLoad()` is called just before an object is initialized, so the object has no uuid or anything else with would be needed to decide on principals authorisation. A row based access control mechanism is required, see [[HibernateSpringAndRowlevelSecurity]]
95 4 Andreas Kohlbecker
96
97 22 Andreas Kohlbecker
### Authorisation evaluation
98
99
100 41 Andreas Kohlbecker
One of the central classes for the evaluation of Roles and CdmAuthorities is the `CdmPermissionEvluator` with implements the `org.springframework.security.access.PermissionEvaluator@. The method @public boolean hasPermission(Authentication authentication, Object targetDomainObject, Object permission)` will always return true if the authentication has the role `ROLE_ADMIN` otherwise decission making is delegated to a `AccessDecisionManager` which should be `UnanimousBasedUnrevocable@. This @AccessDecisionManager` polls all configured AccessDecisionVoters grants access if only grant (or abstain) votes were received. The `AccessDecisionManager` then asks the set of plugged in **@AccessDecisionVoter@s*. The cdm specific voters are found in the package eu.etaxonomy.cdm.persistence.hibernate.permission.voter. For actual configuration details please see the *persistence_security.xml** , here is an example: 
101 22 Andreas Kohlbecker
102 1 Andreas Kohlbecker
~~~
103 41 Andreas Kohlbecker
<bean id="accessDecisionManager" class="org.springframework.security.access.vote.UnanimousBasedUnrevocable">
104 22 Andreas Kohlbecker
        <property name="decisionVoters">
105
            <list>
106
                <bean class="eu.etaxonomy.cdm.persistence.hibernate.permission.voter.GrantAlwaysVoter" />
107
                <bean class="eu.etaxonomy.cdm.persistence.hibernate.permission.voter.TaxonNodeVoter" />
108
                <bean class="eu.etaxonomy.cdm.persistence.hibernate.permission.voter.TaxonBaseVoter" />
109
                <bean class="eu.etaxonomy.cdm.persistence.hibernate.permission.voter.DescriptionBaseVoter" />
110
                <bean class="eu.etaxonomy.cdm.persistence.hibernate.permission.voter.DescriptionElementVoter" />
111
            </list>
112
        </property>
113
</bean>
114
115
<!--
116 41 Andreas Kohlbecker
    CdmPermissionEvaluator.hasPermissions() evaluates the CdmPermissions like TAXONNODE.[UPDATE]{20c8f083-5870-4cbd-bf56-c5b2b98ab6a7}
117 22 Andreas Kohlbecker
-->
118
<bean id="cdmPermissionEvaluator" class="eu.etaxonomy.cdm.persistence.hibernate.permission.CdmPermissionEvaluator">
119
    <property name="accessDecisionManager" ref="accessDecisionManager" />
120
</bean>
121
~~~
122 26 Andreas Kohlbecker
123
#### AccessDecisionVoters
124
125
As briefly described above, the AccessDecisionVoters are crucial for finding a decision on whether a user is allowed to perform an operation on a specific cdm object or class of cdm objects. The operations are the so called CRUD operations. This acronym refers to Create, Read, Update, Delete. 
126 1 Andreas Kohlbecker
127
A user can have one or multiple granted authorities, for more information on granted authorities please refer to the paragraph [[CdmAuthorisationAndAccessControl#CdmAuthority|CdmAuthority]] above. All voters will cast votes on all granted authorities a user has.
128 35 Andreas Kohlbecker
129 1 Andreas Kohlbecker
In the following we will just use the term voter as a short form for AccessDecisionVoter. 
130
131
Voters can cast three different vote:
132
133
* Allow
134
* Deny 
135
* Abstain
136
137
In order to make a access decision the AccessDecisionVoters are asked sequentially to cast their vote. If at least one voter casts _Deny_ the the whole operation will be denied. This behaviour is guaranteed by the `GrantAlwaysVoter` which will always cast an _Allow_.
138
139
All AccessDecisionVoters are responsible for a specific class of data entities and thus it will only cast an _Allow_ or _Deny_ vote when an operation on an object of this class is to be performed. If a voter is not responsible it will _Abstain_. If a voter "feels" not responsible it casts an _Abstain_. As a consequence of this concept everything is allowed unless a voter is responsible for a specific object class. Only in this case there is the potential that an operation will be denied.
140
141
Generally each of the voters will check if the user has a granted authority which matches the the operation and object. Voters can also perform additional checks (see TaxonNodeVoter, DescriptionElementVoter) which can take related objects into account (parent taxon nodes) or specific properties of of Objects (feature of description element).
142
143
List of existing AccessDecisionVoters in the order of their execution:
144
  
145
1. TaxonNodeVoter: 
146
  * responsible for TaxonNode
147
  * allows if voter is responsible for the object class in question and
148
    1. if the user has a granted authority for that specific object or for all objects of this class which matches the operation to be performed
149
    1. or if the user has a matching granted authority for any of the parent taxon nodes in the classification (e.g.: @TAXONNODE.UPDATE{20c8f083-5870-4cbd-bf56-c5b2b98ab6a7@})
150
  * denies otherwise
151
1. TaxonBaseVoter:  
152
  * responsible for Taxon, Synonym
153
  * allows if voter is responsible for the object class in question and
154
    1. if the user has a granted authority for that specific object or for all objects of this class which matches the operation to be performed (e.g.: @TAXONBASE.UPDATE@)
155
  * denies otherwise
156
1. DescriptionBaseVoter:  
157
  * responsible for TaxonDescription, SpecimenDescription
158
  * allows if voter is responsible for the object class in question and
159
    1. if the user has a granted authority for that specific object or for all objects of this class which matches the operation to be performed (e.g.: @DESCRIPTIONBASE.UPDATE@)
160
  * denies otherwise
161
1. DescriptionElementVoter:  
162
  * responsible for all types of DescriptionElements
163
  * allows if voter is responsible for the object class in question and
164
    1. if the user has a granted authority for that specific object or for all objects of this class which matches the operation to be performed
165
    1. if the the operation to be preformed is specific to the Feature of the Description Element and if the _Property_ of one of the users granted authorities matches this Feature. (e.g.: @DESCRIPTIONELEMENTBASE(Ecology).[UPDATE]@)
166
  * denies otherwise
167
168 58 Andreas Kohlbecker
## Cdm Entity access control
169
170
### Type bases access control
171
172
This is defined through the general *CdmAuthotities* which are not referring to a specific entity uuid.
173
174
### Per entity access control
175
176
This is defined through the entity specific *CdmAuthotities* which referring to a specific entity by the uuid.
177
178
### Extended create permission problem
179
180
for e general discussion see #4305 (newly created entities must stay editable even if a user only has the permission to create them)  for details regarding the current implementation see #6867 (explicitely assign and revoke UPDATE & DELETE permission per enitity in the registration workflow). Problems with the current implementation: #7147, ...
181
182
183 1 Andreas Kohlbecker
## Web service access control
184
185
### Authentication
186
187
All web service end points which require authentication support http basic.
188
189
There are two sources of users:
190
191 56 Andreas Kohlbecker
**CDM users**: 
192
193
The users stored in the cdm database
194
195
**Global managing users**: 
196
 
197
Users stored in the Managing users properties file (`$HOME/.cdmLibrary/managing-users.properties`). This is a java properties file to populate the InMemoryUserDetailsManager in any of the cdm-remote instances with special global management users which are granted to access special web services. Among these are the /manage/ web services and those triggering long running tasks. Global management users have the role **ROLE_MANAGE_CLIENT** and will be available in each of the cdm-remote instances. Changes made to this file are applied after restarting a cdm instance. For implementation details please refer to #6248.
198
199
Web service endpoints accessible to global managing users:
200
201
* `/manage/**`
202
* `/**description/accumulateDistributions`
203 52 Andreas Kohlbecker
204
### Authorization
205
206
1. Classical spring security authorization as described above
207 53 Andreas Kohlbecker
1. OAuth2: see #6118 *evaluate spring-security-auth2 and spring-cloud-security as a framework for OAuth2*
208 52 Andreas Kohlbecker
209
## Use cases
210
211
 A. a specific **classification sub tree** is **publicly visible** that is it is _published_
212
 B. a specific **classification sub tree** must not be **publicly visible** in the data portal and thus must be also hidden in the web service responses
213
 C. a specific **classification sub tree** is only visible for users which have a specific **role** but the user is not granted to **edit** anything in/below it
214
 D. A user is only granted to **edit Descriptions** 
215
 E. A user is only granted to **edit DescriptionElements** of a specific _Feature_ 
216
 F. A user is only granted to **edit structured Descriptions** 
217
 G. Combinations of B, C and D, E must be possible
218
 H. Only users with the **roles** *Admin* or **Usermanager** or the user in question it self (if currently authenticated) are allowed to execute **change password** 
219
 I. Only users with the **roles** *Admin* or **Usermanager** are allowed to create or **edit** new users
220
221
~~~
222
<code class="rst">
223
Tabular summary of above use cases translated into roles:
224
225
===========  =========================  ======================================  ===============  =============================
226
\                                                                               what to protect
227
-----------  -------------------------  --------------------------------------  ----------------------------------------------
228
Usecase      Role                       authority string                        Entity            ServiceMethod
229
===========  =========================  ======================================  ===============  =============================
230
A.           Anonymous                  TaxonNode.[READ]{uuid}                     ...
231
B.           TaxGroupX_User             TaxonNode.[READ]{uuid}                     ...
232
C.           TaxGroupX_Editor           TaxonNode.[UPDATE]{uuid}                   ...
233
D.           DescriptionEditor		Description.[UPDATE]			 ...					
234
E.           DescriptionEditor		DescriptioElement(Ecology).[UPDATE]        ...					
235
H.           Admin, Usermanager                                                                  UserService.changePassword()
236
===========  =========================  ======================================  ===============  =============================
237
238
*Anonymous* means not authenticated  
239
240
~~~
241
242
 **Special cases:** 
243 1 Andreas Kohlbecker
244 52 Andreas Kohlbecker
* **@TaxonNames@** can potentially be shared between different taxa, thus a situation may occur where a user has grants to edit taxon A but not for taxon B, but both taxa are sharing the same name. How will we handle this situation, should the name be cloned when the user starts editing taxon A, so that taxon A has another name entity than taxon B after the user saved the latest changes?
245 53 Andreas Kohlbecker
* The same problem as described above for TaxonNames also accounts for *@References@*, but in this case the problem is more severe since references are very often part of multiple taxon names.