Changes in 7e71730: Several documentation improvements/fixes

				wiki/info/security/permission-migration-tests.md
			
          @@ -3,26 +3,26 @@

           ## Introduction

           The following document describes which parts of the security and domain model are being migrated when starting a server with pre-existing data for the first time with a permission vertical enabled version.

          -In addition, several concrete scenarios that need to get checked when doing migration testing for permission vertical are documented.

          +In addition, several scenarios that need to get checked when doing migration testing for permission vertical are documented.

           ## Migration details regarding the security model

           ### Server group and server configuration

           In the new permission system, the server is explicitly modeled as a type having an ownership and ACL.

          -Server specific permission checks can be qualified by the server name. To make this convenient, a group is created named by the server with the suffix "-server". This group is the initial owner of the server, which means, any server admin may configure local server configurations (e.g. making the server public).

          +Server specific permission checks can be qualified by the server name. To make this convenient, a group is created named like the server with the suffix "-server". This group is the initial owner of the server, which means, any server admin may configure local server configurations (e.g. making the server public).

          -In addition, the created server group is initially set up to grant the role "sailing_viewer" with forAll=true. This means, objects owned by the server group will be readable by everyone (including anonymous users). Speaking of event servers or the archive server, this is consistent to the previous behavior where all events where publicly visible. Servers meant to be only visible to a specific group may be configured differently after migration.

          +In addition, the created server group is initially set up to grant the role "sailing_viewer" with forAll=true. This means, objects owned by the server group will be readable by everyone (including anonymous users). For event servers or the archive server, this is consistent to the previous behavior where all events where publicly visible. Servers meant to be only visible to a specific group may be configured differently after migration.

          -There is another new semantic introduced called Self-Service. This is implemented by granting the "CREATE_OBJECT" action to the null group of the server object. This allows newly created users to create domain objects in their own owned space. This option is intended to be off for new as well as migrated servers.

          +There is another new semantic introduced called Self-Service. This is implemented by granting the "CREATE_OBJECT" action to the null group of the server object. This allows newly created users to create domain objects in their own owned space. This option is intended to be off by default.

           ### Specific <all> user

          -A user named <all> is created during migration. This user has no account set to make it impossible to log into this user.

          +A user named <all> is created during migration. This user has no account making it impossible to log into this user.

           Instead this user is used for any permission check in addition to the real user. This is also the case for anonymous users.

           Any permissions directly or indirectly associated with the <all> user will be usable by anyone.

          -### All users

          +### Existing users

           All pre existing users will receive the following additions:

          @@ -51,14 +51,14 @@ There are several RoleDefinitions that are automatically created for new or migr

           These roles are system roles that are intended to be used by any user. To ensure this, an ACL entry is generated for those roles granting action "READ" to the null group (all users).

          -Most of those RoleDefinitions also existed in the old model as roles (all but sailing_viewer). on existing servers, users having any predefined role, need to get an equivalent role associated. Any user having one of these roles (excluding the "admin" case described above) will have the new version of this role qualified by the server's default group.

          -This means those users will still have the same permissions bust only for objects owned by the mentioned server group.

          +Most of those default RoleDefinitions also had role with the same name in the old role model (all but sailing_viewer). On existing servers, users having any old role, need to get an equivalent role associated. Any user having one of these old roles (excluding the "admin" case described below) will have the new version of this role qualified by the server's default group associated.

          +This means those users should still have equivalent permissions but only for objects owned by the mentioned server group.

           Any other role would be lost. This is most probably an unlikely case due to the fact that the old permission UI had no possibility to define new roles.

           ### Tenants

          -Existing users (including the "admin" but excluding "<all>) will automatically get a UserGroup created named like the user with the suffix "-tenant". This menas the admin's tenant is called "admin-tenant".

          +Existing users (including the "admin" but excluding "<all>) will automatically get a UserGroup created named like the user with the suffix "-tenant". This means the admin's tenant is called "admin-tenant".

           ### Default creation tenant

          @@ -66,9 +66,9 @@ We introduced a new concept called "default creation tenant" to the security mod

           The "admin" user is the only user that will get the server group set as default creation tenant for that server. For the admin user this is the right setting for most cases. Any other user will have it's tenant set as default creation tenant.

          -### Users having "admin" role

          +### Users having the old "admin" role

          -Any user having the role "admin" will be added as a member of the server's group. Members of a group can set this group as their default creation tenant for the server. On a public server it is intended that all event data is owned by the server's group to ensure that these domain objects are publicly readable. To help prevent typical misconfigurations any user logging in to the admin console on a public server who has not set the server group as default creation group on that server will see a warning. Any member of that group will be asked if this should be fixed automatically.

          +Any user having the old role "admin" will be added as a member of the server's group. Members of a group can set this group as their default creation tenant for the server. On a public server it is intended that all event data is owned by the server's group to ensure that these domain objects are publicly readable. To help prevent typical misconfigurations any user logging in to the admin console on a public server who has not set the server group as default creation group will see a warning. Any member of that group will be asked if this should be fixed automatically.

           ### Special role sailing_viewer

          @@ -76,7 +76,7 @@ Before permission vertical, most parts of the website were completely unsecured.

           ### Ownerships

          -Any security and domain object being loaded will receive an initial ownership. The inital owning group is the server's default group while no owning user is set in most cases (users own themselves and their tenant group). Making the server's default group own those objects will ensure that any admin on that server who is migrated as an admin qualified by the server group will still be able to manage those objects. While retaining the permissions for objects on that server, it is save to import several migrated user stores to a central one because those permissions do not include objects of other servers.

          +Any security and domain object being loaded will receive an initial ownership. The inital owning group is the server's default group while no owning user is set in most cases (users own themselves and their tenant group). Making the server's default group own those objects will ensure that any admin on that server will still be able to manage those objects. Due to the scoping of all migrated admin roles by the server, it is safe to import several migrated user stores to a central one because those permissions do not affect objects of other servers.

           ### ACLs

          @@ -86,7 +86,7 @@ The only ACLs that are automatically created on migration or server initializati

           In general, permission of a user are not removed during migration. In most cases those permissions will be useless after migration because the former lower case permissions will not match the newer case sensitive/upper case permissions.

          -The only widely used permission is "data_mining" for which we have specific handling. Any user having this permission will have the equivalent perrmission "SERVER:DATA_MINING" with a qualification by the server's name. Again, this means that such a permission is save in case of an import of several user stores because the migrated permission does not affect other servers.

          +The only widely used permission is "data_mining" for which we have specific handling. Any user having this permission will have the equivalent permission "SERVER:DATA_MINING" with a qualification by the server's name. Again, this means that such a permission is safe in case of an import of several user stores because the migrated permission does not affect other servers.

           ## Basic verification for initial and migrated servers

          @@ -102,7 +102,7 @@ The following criteria must be fulfilled for new or initially migrated servers a

           ## Domain and security object migration

          -Some of the semantics described above will apply to all objects being part a security type. Those semantics need to get checked not only for security related objects but also for domain objects.

          +Some of the semantics described above will apply to all objects being part of a security type. Those semantics need to get checked not only for security related objects but also for domain objects.

           ### Verification of security effects to the basic domain 

          @@ -131,7 +131,7 @@ Test users for the following scenarios need to be created:

           ### Verification of test user migration

          -In addition for the verifications for the basic security model (decribed above) the following verifications regarding the security model need to be done for migrated servers.

          +In addition for the verifications for the basic security model (described above) the following verifications regarding the security model need to be done for migrated servers.

           * In general, the migration rules for users documented above need to be checked

           * Going to the user profile for the "admin" user, the default creation tenant needs to be set to the server group initially

          @@ -145,16 +145,16 @@ In addition for the verifications for the basic security model (decribed above) 

           ### verification

           TODO:

          -* one user creates event model -> not visible by another user

          +* one user creates an event model -> not visible by another user

           * one user adds another user by name to his group and adds "sailing_viewer" to his group -> stuff needs to be visible to the other user, but not editable

           ## Changed semantics in the sse model

          -The semantics (requirements and behavior) of several parts of the sse model was changed based on the new security model.

          +The semantics (requirements and behavior) of several parts of the sse model were changed based on the new security model.

           ### Master Data Import (MDI)

          -Due to the fact that servers and their data are now secured by default, the interface providing data on existing servers during MDI is also affected. To make it possible to import data from secured servers, credentials may now be given in the MDI import. Those credentials need to be valid on the target server and provide all the required READ permissions for the data intended to be imported.

          +Due to the fact that servers and their data are now secured by default, the interface providing data on existing servers during MDI is also affected. To make it possible to import data from secured servers, credentials must now be given in the MDI import. Those credentials need to be valid on the target server and provide all the required READ permissions for the data intended to be imported.

           ### Replication

          @@ -176,7 +176,7 @@ When races are automatically tracked during server restarting, the accounts are 

           ### DeviceConfiguration UUID

          -DeviceConsigurations for the race manager app were changed to now have an identifying UUID. As a fallback behavior, the name is also usable to login to such a device configuration. The REAST API was extended to accept both values to associate a device to a configuration. Both app versions (an old build and one that includes the security model change) need to be able to connect to both server versions.

          +DeviceConfigurations for the race manager app were changed to now have an identifying UUID. As a fallback behavior, the name is also usable to login to such a device configuration. The REST API was extended to accept both values to associate a device to a configuration. Both app versions (an old build and one that includes the security model change) need to be able to connect to both server versions.

           ### Verification scenarios of changed sailing semantics

          @@ -188,7 +188,7 @@ This chapter is intended to sum up the aspects to be tested along specific deplo

           ### Migrate a public server with a big amount of historic event data (aka archive migration)

          -A server with a big amount of historic event data needs to get migrated to the new security model. After the initial loading is finished, the following verifications need to be done. This scenario is intended to be focussed on the following aspects:

          +A server with a big amount of historic event data needs to get migrated to the new security model. After the initial loading is finished, the following verifications need to be done. This scenario is intended to be focused on the following aspects:

           * migration of existing data

           * consistent restore of data

          @@ -202,7 +202,7 @@ To verify that all data is migrated as intended, several checks need to get fulf

           * The loaded TrackedRaces need to exactly match the old server

           * All existing domain data is shown in tables and provides the full set of actions

           * Identify regattas that are tracked using the various tracking technologies (TracTrac, Swiss Timing, Smartphone Tracking) and verify the correctness regarding the following aspects:

          -    * On the Homepage verify statistics, wind information, results, contens of the leaderboard

          +    * On the Homepage verify statistics, wind information, results, contents of the leaderboard

               * Show the stand-alone leaderboard and verify the contents

           * External servers need to still be referenced

           * Several technical parts of the AdminConsole need to be accessible and provide all available actions:

          @@ -293,7 +293,7 @@ In addition to the tracking tests, this setup needs to get managed by the race m

           ### Public self-service setup

          -An additional deployment scenario is the self-service case that will be covered by my.sapsailing.com. This case is already well covered from the perspective of the app development but several backend-focussed validations need ensured as well. The following scenarios need to be covered:

          +An additional deployment scenario is the self-service case that will be covered by my.sapsailing.com. This case is already well covered from the perspective of the app development but several backend-focused validations need to be ensured as well. The following scenarios need to be covered:

           * Setup and management of open regattas from the App and AdminConsole

           * Inviting others to track

...	...	@@ -3,26 +3,26 @@
3	3	## Introduction
4	4
5	5	The following document describes which parts of the security and domain model are being migrated when starting a server with pre-existing data for the first time with a permission vertical enabled version.
6		-In addition, several concrete scenarios that need to get checked when doing migration testing for permission vertical are documented.
	6	+In addition, several scenarios that need to get checked when doing migration testing for permission vertical are documented.
7	7
8	8	## Migration details regarding the security model
9	9
10	10	### Server group and server configuration
11	11
12	12	In the new permission system, the server is explicitly modeled as a type having an ownership and ACL.
13		-Server specific permission checks can be qualified by the server name. To make this convenient, a group is created named by the server with the suffix "-server". This group is the initial owner of the server, which means, any server admin may configure local server configurations (e.g. making the server public).
	13	+Server specific permission checks can be qualified by the server name. To make this convenient, a group is created named like the server with the suffix "-server". This group is the initial owner of the server, which means, any server admin may configure local server configurations (e.g. making the server public).
14	14
15		-In addition, the created server group is initially set up to grant the role "sailing_viewer" with forAll=true. This means, objects owned by the server group will be readable by everyone (including anonymous users). Speaking of event servers or the archive server, this is consistent to the previous behavior where all events where publicly visible. Servers meant to be only visible to a specific group may be configured differently after migration.
	15	+In addition, the created server group is initially set up to grant the role "sailing_viewer" with forAll=true. This means, objects owned by the server group will be readable by everyone (including anonymous users). For event servers or the archive server, this is consistent to the previous behavior where all events where publicly visible. Servers meant to be only visible to a specific group may be configured differently after migration.
16	16
17		-There is another new semantic introduced called Self-Service. This is implemented by granting the "CREATE_OBJECT" action to the null group of the server object. This allows newly created users to create domain objects in their own owned space. This option is intended to be off for new as well as migrated servers.
	17	+There is another new semantic introduced called Self-Service. This is implemented by granting the "CREATE_OBJECT" action to the null group of the server object. This allows newly created users to create domain objects in their own owned space. This option is intended to be off by default.
18	18
19	19	### Specific <all> user
20	20
21		-A user named <all> is created during migration. This user has no account set to make it impossible to log into this user.
	21	+A user named <all> is created during migration. This user has no account making it impossible to log into this user.
22	22	Instead this user is used for any permission check in addition to the real user. This is also the case for anonymous users.
23	23	Any permissions directly or indirectly associated with the <all> user will be usable by anyone.
24	24
25		-### All users
	25	+### Existing users
26	26
27	27	All pre existing users will receive the following additions:
28	28
...	...	@@ -51,14 +51,14 @@ There are several RoleDefinitions that are automatically created for new or migr
51	51
52	52	These roles are system roles that are intended to be used by any user. To ensure this, an ACL entry is generated for those roles granting action "READ" to the null group (all users).
53	53
54		-Most of those RoleDefinitions also existed in the old model as roles (all but sailing_viewer). on existing servers, users having any predefined role, need to get an equivalent role associated. Any user having one of these roles (excluding the "admin" case described above) will have the new version of this role qualified by the server's default group.
55		-This means those users will still have the same permissions bust only for objects owned by the mentioned server group.
	54	+Most of those default RoleDefinitions also had role with the same name in the old role model (all but sailing_viewer). On existing servers, users having any old role, need to get an equivalent role associated. Any user having one of these old roles (excluding the "admin" case described below) will have the new version of this role qualified by the server's default group associated.
	55	+This means those users should still have equivalent permissions but only for objects owned by the mentioned server group.
56	56
57	57	Any other role would be lost. This is most probably an unlikely case due to the fact that the old permission UI had no possibility to define new roles.
58	58
59	59	### Tenants
60	60
61		-Existing users (including the "admin" but excluding "<all>) will automatically get a UserGroup created named like the user with the suffix "-tenant". This menas the admin's tenant is called "admin-tenant".
	61	+Existing users (including the "admin" but excluding "<all>) will automatically get a UserGroup created named like the user with the suffix "-tenant". This means the admin's tenant is called "admin-tenant".
62	62
63	63	### Default creation tenant
64	64
...	...	@@ -66,9 +66,9 @@ We introduced a new concept called "default creation tenant" to the security mod
66	66
67	67	The "admin" user is the only user that will get the server group set as default creation tenant for that server. For the admin user this is the right setting for most cases. Any other user will have it's tenant set as default creation tenant.
68	68
69		-### Users having "admin" role
	69	+### Users having the old "admin" role
70	70
71		-Any user having the role "admin" will be added as a member of the server's group. Members of a group can set this group as their default creation tenant for the server. On a public server it is intended that all event data is owned by the server's group to ensure that these domain objects are publicly readable. To help prevent typical misconfigurations any user logging in to the admin console on a public server who has not set the server group as default creation group on that server will see a warning. Any member of that group will be asked if this should be fixed automatically.
	71	+Any user having the old role "admin" will be added as a member of the server's group. Members of a group can set this group as their default creation tenant for the server. On a public server it is intended that all event data is owned by the server's group to ensure that these domain objects are publicly readable. To help prevent typical misconfigurations any user logging in to the admin console on a public server who has not set the server group as default creation group will see a warning. Any member of that group will be asked if this should be fixed automatically.
72	72
73	73	### Special role sailing_viewer
74	74
...	...	@@ -76,7 +76,7 @@ Before permission vertical, most parts of the website were completely unsecured.
76	76
77	77	### Ownerships
78	78
79		-Any security and domain object being loaded will receive an initial ownership. The inital owning group is the server's default group while no owning user is set in most cases (users own themselves and their tenant group). Making the server's default group own those objects will ensure that any admin on that server who is migrated as an admin qualified by the server group will still be able to manage those objects. While retaining the permissions for objects on that server, it is save to import several migrated user stores to a central one because those permissions do not include objects of other servers.
	79	+Any security and domain object being loaded will receive an initial ownership. The inital owning group is the server's default group while no owning user is set in most cases (users own themselves and their tenant group). Making the server's default group own those objects will ensure that any admin on that server will still be able to manage those objects. Due to the scoping of all migrated admin roles by the server, it is safe to import several migrated user stores to a central one because those permissions do not affect objects of other servers.
80	80
81	81	### ACLs
82	82
...	...	@@ -86,7 +86,7 @@ The only ACLs that are automatically created on migration or server initializati
86	86
87	87	In general, permission of a user are not removed during migration. In most cases those permissions will be useless after migration because the former lower case permissions will not match the newer case sensitive/upper case permissions.
88	88
89		-The only widely used permission is "data_mining" for which we have specific handling. Any user having this permission will have the equivalent perrmission "SERVER:DATA_MINING" with a qualification by the server's name. Again, this means that such a permission is save in case of an import of several user stores because the migrated permission does not affect other servers.
	89	+The only widely used permission is "data_mining" for which we have specific handling. Any user having this permission will have the equivalent permission "SERVER:DATA_MINING" with a qualification by the server's name. Again, this means that such a permission is safe in case of an import of several user stores because the migrated permission does not affect other servers.
90	90
91	91	## Basic verification for initial and migrated servers
92	92
...	...	@@ -102,7 +102,7 @@ The following criteria must be fulfilled for new or initially migrated servers a
102	102
103	103	## Domain and security object migration
104	104
105		-Some of the semantics described above will apply to all objects being part a security type. Those semantics need to get checked not only for security related objects but also for domain objects.
	105	+Some of the semantics described above will apply to all objects being part of a security type. Those semantics need to get checked not only for security related objects but also for domain objects.
106	106
107	107	### Verification of security effects to the basic domain
108	108
...	...	@@ -131,7 +131,7 @@ Test users for the following scenarios need to be created:
131	131
132	132	### Verification of test user migration
133	133
134		-In addition for the verifications for the basic security model (decribed above) the following verifications regarding the security model need to be done for migrated servers.
	134	+In addition for the verifications for the basic security model (described above) the following verifications regarding the security model need to be done for migrated servers.
135	135
136	136	* In general, the migration rules for users documented above need to be checked
137	137	* Going to the user profile for the "admin" user, the default creation tenant needs to be set to the server group initially
...	...	@@ -145,16 +145,16 @@ In addition for the verifications for the basic security model (decribed above)
145	145	### verification
146	146
147	147	TODO:
148		-* one user creates event model -> not visible by another user
	148	+* one user creates an event model -> not visible by another user
149	149	* one user adds another user by name to his group and adds "sailing_viewer" to his group -> stuff needs to be visible to the other user, but not editable
150	150
151	151	## Changed semantics in the sse model
152	152
153		-The semantics (requirements and behavior) of several parts of the sse model was changed based on the new security model.
	153	+The semantics (requirements and behavior) of several parts of the sse model were changed based on the new security model.
154	154
155	155	### Master Data Import (MDI)
156	156
157		-Due to the fact that servers and their data are now secured by default, the interface providing data on existing servers during MDI is also affected. To make it possible to import data from secured servers, credentials may now be given in the MDI import. Those credentials need to be valid on the target server and provide all the required READ permissions for the data intended to be imported.
	157	+Due to the fact that servers and their data are now secured by default, the interface providing data on existing servers during MDI is also affected. To make it possible to import data from secured servers, credentials must now be given in the MDI import. Those credentials need to be valid on the target server and provide all the required READ permissions for the data intended to be imported.
158	158
159	159	### Replication
160	160
...	...	@@ -176,7 +176,7 @@ When races are automatically tracked during server restarting, the accounts are
176	176
177	177	### DeviceConfiguration UUID
178	178
179		-DeviceConsigurations for the race manager app were changed to now have an identifying UUID. As a fallback behavior, the name is also usable to login to such a device configuration. The REAST API was extended to accept both values to associate a device to a configuration. Both app versions (an old build and one that includes the security model change) need to be able to connect to both server versions.
	179	+DeviceConfigurations for the race manager app were changed to now have an identifying UUID. As a fallback behavior, the name is also usable to login to such a device configuration. The REST API was extended to accept both values to associate a device to a configuration. Both app versions (an old build and one that includes the security model change) need to be able to connect to both server versions.
180	180
181	181	### Verification scenarios of changed sailing semantics
182	182
...	...	@@ -188,7 +188,7 @@ This chapter is intended to sum up the aspects to be tested along specific deplo
188	188
189	189	### Migrate a public server with a big amount of historic event data (aka archive migration)
190	190
191		-A server with a big amount of historic event data needs to get migrated to the new security model. After the initial loading is finished, the following verifications need to be done. This scenario is intended to be focussed on the following aspects:
	191	+A server with a big amount of historic event data needs to get migrated to the new security model. After the initial loading is finished, the following verifications need to be done. This scenario is intended to be focused on the following aspects:
192	192
193	193	* migration of existing data
194	194	* consistent restore of data
...	...	@@ -202,7 +202,7 @@ To verify that all data is migrated as intended, several checks need to get fulf
202	202	* The loaded TrackedRaces need to exactly match the old server
203	203	* All existing domain data is shown in tables and provides the full set of actions
204	204	* Identify regattas that are tracked using the various tracking technologies (TracTrac, Swiss Timing, Smartphone Tracking) and verify the correctness regarding the following aspects:
205		- * On the Homepage verify statistics, wind information, results, contens of the leaderboard
	205	+ * On the Homepage verify statistics, wind information, results, contents of the leaderboard
206	206	* Show the stand-alone leaderboard and verify the contents
207	207	* External servers need to still be referenced
208	208	* Several technical parts of the AdminConsole need to be accessible and provide all available actions:
...	...	@@ -293,7 +293,7 @@ In addition to the tracking tests, this setup needs to get managed by the race m
293	293
294	294	### Public self-service setup
295	295
296		-An additional deployment scenario is the self-service case that will be covered by my.sapsailing.com. This case is already well covered from the perspective of the app development but several backend-focussed validations need ensured as well. The following scenarios need to be covered:
	296	+An additional deployment scenario is the self-service case that will be covered by my.sapsailing.com. This case is already well covered from the perspective of the app development but several backend-focused validations need to be ensured as well. The following scenarios need to be covered:
297	297
298	298	* Setup and management of open regattas from the App and AdminConsole
299	299	* Inviting others to track