Fossil SCM

Rewrote the login-groups doc, making it both more clear and more detailed. This started out as clarifying a confusion brought up [forum:/forumpost/beba7d4e78c943d0 | on the forum], but experimentation kept bringing up new and interesting restrictions and interactions that I felt were worth documenting.

wyoung 2022-04-20 14:59 trunk
Commit 697cf6fb354d0ce69a46a8b4a96b08b8f112e9bb0374ae73c5127e868ba2aa95
Parent a42f5af812aaabf…
1 file changed +118 -20
~ www/caps/login-groups.md
M www/caps/login-groups.md
+118 -20
--- www/caps/login-groups.md
+++ www/caps/login-groups.md
@@ -1,32 +1,130 @@
11
 # Login Groups
22
33
 The Admin → Login-Groups UI feature and its corresponding [`login-group`
44
 command][lg] solve a common problem with Fossil: you’ve created multiple
5
-repositories that some set of users all need access to, those users all
6
-have the same access level on all of these shared repositories, and you
7
-don’t want to redundantly configure the user set for each repository.
5
+repositories that some subset of users need access to, and you
6
+don’t want to redundantly administer the user credentials for each
7
+repository.
8
+
9
+
10
+## Restrictions
811
912
 This feature ties changes to the “`user`” table in one repo to that in
10
-one or more other repos. With this configured, you get a new choice on
11
-the user edit screen, offering to make changes specific to the one
12
-repository only or to apply it to all others in the login group as well.
13
-
14
-A user can log into one repo in a login group only if that user has an
15
-entry in that repo’s user table. That is, setting up a login group
16
-doesn’t automatically transfer all user accounts from the joined repo to
17
-the joining repo. Only when a user exists by name in both repos will
18
-that user be able to share credentials across the repos.
19
-
20
-Login groups can have names, allowing one “master” repo to host multiple
21
-subsets of its users to other repos.
22
-
23
-Trust in login groups is transitive within a single server. If repo C
24
-joined repo B and repo B joined A, changes in C’s user table affect both
25
-A and B, if you tell Fossil that the change applies to all repos in the
26
-login group.
13
+one or more other repos, keyed by the user’s name. The interactions are
14
+non-obvious because although the goal is for the end result to “just
15
+work,” there are practical security and administration matters that
16
+complicate things:
17
+
18
+1. Login group handling only works between joined repositories for the
19
+ subset of users with the same name.
20
+
21
+1. If you’re logged in on one repo in a group, any other repo in that
22
+ group that has a matching user record will accept your valid login.
23
+
24
+1. When you set up a login group between two repos, the user tables
25
+ aren’t merged, so even though you may have users that appear in
26
+ both, they will retain their initial passwords, credentials, and so
27
+ forth.
28
+
29
+1. The same is true after the login group is created: changes you make
30
+ to the user table in one repo in the group only propagate to the
31
+ other repos in the group when you check the “Apply changes to all
32
+ repositories“ box in the “Scope” section of the user edit screen.
33
+ Otherwise, user changes remain local to the repo you made them on.
34
+
35
+1. Login groups only affect [the HTTP interfaces][wo]. Contrast things
36
+ like `ssh://` clones, where unless you [go out of your way][sh] to
37
+ force them to run over one of the HTTP interfaces that pays
38
+ attention to Fossil’s RBAC system, login groups aren’t consulted.
39
+
40
+
41
+## Interactions
42
+
43
+These restrictions combine in subtle and interesting ways. Examples:
44
+
45
+* **#1 and #2**: If you are logged into repo C as “charlie” and then
46
+ try to visit joined repo A where “charlie” doesn’t exist, your valid
47
+ login on C won’t get you into A.
48
+
49
+* **#2 and #3**: If “alice” exists in both of these same repos,
50
+ logging in on A gets her into C, but if she has different user
51
+ capabilities on each from the time before the two repos joined the
52
+ login group, her caps on A don’t apply to C, nor vice versa.
53
+
54
+ Let us say F is a forum-only repo, and W is a wiki-only repo, and
55
+ that Alice has forum-posting rights on F and wiki-editing rights on
56
+ W. If both repos are joined by a login group, Alice can log in on F
57
+ and then access W without logging in on it separately, but she
58
+ cannot then post a forum message on W even though she could on F.
59
+
60
+* **#3 and #4**: If you change the caps for user “alice” on one repo
61
+ in a group and tell Fossil to apply the changes to all repos in the
62
+ group, the new caps will *overwrite* those on the other repos, not
63
+ merge with them.
64
+
65
+ To extend the practical example from the prior point, let us say you
66
+ wish to grant Alice the “write unversioned” capability on both F and
67
+ W. If you check that single user cap box on F plus the “apply to
68
+ all” option, then “Apply Changes,” she will end up with forum +
69
+ unversioned caps on repo W, losing her wiki-editing caps in the
70
+ process.
71
+
72
+ If you want user caps to differ on each repo, you must administer
73
+ them separately even if there is a common subset of caps between all
74
+ repos in the group for that user. Remember: selecting the “apply to
75
+ all” box calls for an overwrite operation, not a merge.
76
+
77
+* **#4 and #1**: If you make a change to an existing user “bob” in
78
+ repo B and select the “apply to all” option, it will only affect
79
+ other repos in the group that have a user “bob” configured.
80
+
81
+ But, if you are instead creating user “bob” for the first time and
82
+ select that option, that user *will* be created in all repos. The
83
+ same is true of user deletion: that destructive action will
84
+ propagate through the group if you request it.
85
+
86
+* **#5 and #1**: If you have a user “daisy” on both repos A and B in a
87
+ login group, logging in over the web to A doesn’t let you push
88
+ changes into B over SSH. Without the workaround linked above, SSH
89
+ only pays attention to the operating system’s user authentication
90
+ system, not Fossil’s.
91
+
92
+ Inversely, if Daisy successfully logs in over SSH to repo B, she
93
+ gains no access to any of the other repos in that group. She needs
94
+ at least one valid login over HTTP to one of the group’s repos.
95
+
96
+
97
+## Discussion
98
+
99
+The end result of all of this is that you can have a subset of users
100
+with credentials only on repo A, a different subset only on B, and a
101
+third subset common to both. The only thing selecting which case applies
102
+is restriction #1 above.
103
+
104
+Login groups have names. A repo can be in only one of these named login
105
+groups at a time.
106
+
107
+Trust in login groups is transitive within a single server. Consider
108
+this sequence:
109
+
110
+```
111
+ $ cd /path/to/A/checkout
112
+ $ fossil login-group join --name G ~/museum/B.fossil
113
+ $ cd /path/to/C/checkout
114
+ $ fossil login-group join ~/museum/B.fossil
115
+```
116
+
117
+That creates login group G joining repo A to B, then joins C to B.
118
+Although we didn’t explicitly tie C to A, a successful login on C gets
119
+you into both A and B, within the restrictions set out above.
120
+
121
+Changes are transitive in the same way, provided you check that “apply
122
+to all” box on the user edit screen.
27123
28124
 [lg]: /help?cmd=login-group
125
+[sh]: ../server/any/http-over-ssh.md
126
+[wo]: ./index.md#webonly
29127
30128
 -----
31129
32130
 *[Back to Administering User Capabilities](./)*
33131
--- www/caps/login-groups.md
+++ www/caps/login-groups.md
@@ -1,32 +1,130 @@
1 # Login Groups
2
3 The Admin → Login-Groups UI feature and its corresponding [`login-group`
4 command][lg] solve a common problem with Fossil: you’ve created multiple
5 repositories that some set of users all need access to, those users all
6 have the same access level on all of these shared repositories, and you
7 don’t want to redundantly configure the user set for each repository.
 
 
 
8
9 This feature ties changes to the “`user`” table in one repo to that in
10 one or more other repos. With this configured, you get a new choice on
11 the user edit screen, offering to make changes specific to the one
12 repository only or to apply it to all others in the login group as well.
13
14 A user can log into one repo in a login group only if that user has an
15 entry in that repo’s user table. That is, setting up a login group
16 doesn’t automatically transfer all user accounts from the joined repo to
17 the joining repo. Only when a user exists by name in both repos will
18 that user be able to share credentials across the repos.
19
20 Login groups can have names, allowing one “master” repo to host multiple
21 subsets of its users to other repos.
22
23 Trust in login groups is transitive within a single server. If repo C
24 joined repo B and repo B joined A, changes in C’s user table affect both
25 A and B, if you tell Fossil that the change applies to all repos in the
26 login group.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
27
28 [lg]: /help?cmd=login-group
 
 
29
30 -----
31
32 *[Back to Administering User Capabilities](./)*
33
--- www/caps/login-groups.md
+++ www/caps/login-groups.md
@@ -1,32 +1,130 @@
1 # Login Groups
2
3 The Admin → Login-Groups UI feature and its corresponding [`login-group`
4 command][lg] solve a common problem with Fossil: you’ve created multiple
5 repositories that some subset of users need access to, and you
6 don’t want to redundantly administer the user credentials for each
7 repository.
8
9
10 ## Restrictions
11
12 This feature ties changes to the “`user`” table in one repo to that in
13 one or more other repos, keyed by the user’s name. The interactions are
14 non-obvious because although the goal is for the end result to “just
15 work,” there are practical security and administration matters that
16 complicate things:
17
18 1. Login group handling only works between joined repositories for the
19 subset of users with the same name.
20
21 1. If you’re logged in on one repo in a group, any other repo in that
22 group that has a matching user record will accept your valid login.
23
24 1. When you set up a login group between two repos, the user tables
25 aren’t merged, so even though you may have users that appear in
26 both, they will retain their initial passwords, credentials, and so
27 forth.
28
29 1. The same is true after the login group is created: changes you make
30 to the user table in one repo in the group only propagate to the
31 other repos in the group when you check the “Apply changes to all
32 repositories“ box in the “Scope” section of the user edit screen.
33 Otherwise, user changes remain local to the repo you made them on.
34
35 1. Login groups only affect [the HTTP interfaces][wo]. Contrast things
36 like `ssh://` clones, where unless you [go out of your way][sh] to
37 force them to run over one of the HTTP interfaces that pays
38 attention to Fossil’s RBAC system, login groups aren’t consulted.
39
40
41 ## Interactions
42
43 These restrictions combine in subtle and interesting ways. Examples:
44
45 * **#1 and #2**: If you are logged into repo C as “charlie” and then
46 try to visit joined repo A where “charlie” doesn’t exist, your valid
47 login on C won’t get you into A.
48
49 * **#2 and #3**: If “alice” exists in both of these same repos,
50 logging in on A gets her into C, but if she has different user
51 capabilities on each from the time before the two repos joined the
52 login group, her caps on A don’t apply to C, nor vice versa.
53
54 Let us say F is a forum-only repo, and W is a wiki-only repo, and
55 that Alice has forum-posting rights on F and wiki-editing rights on
56 W. If both repos are joined by a login group, Alice can log in on F
57 and then access W without logging in on it separately, but she
58 cannot then post a forum message on W even though she could on F.
59
60 * **#3 and #4**: If you change the caps for user “alice” on one repo
61 in a group and tell Fossil to apply the changes to all repos in the
62 group, the new caps will *overwrite* those on the other repos, not
63 merge with them.
64
65 To extend the practical example from the prior point, let us say you
66 wish to grant Alice the “write unversioned” capability on both F and
67 W. If you check that single user cap box on F plus the “apply to
68 all” option, then “Apply Changes,” she will end up with forum +
69 unversioned caps on repo W, losing her wiki-editing caps in the
70 process.
71
72 If you want user caps to differ on each repo, you must administer
73 them separately even if there is a common subset of caps between all
74 repos in the group for that user. Remember: selecting the “apply to
75 all” box calls for an overwrite operation, not a merge.
76
77 * **#4 and #1**: If you make a change to an existing user “bob” in
78 repo B and select the “apply to all” option, it will only affect
79 other repos in the group that have a user “bob” configured.
80
81 But, if you are instead creating user “bob” for the first time and
82 select that option, that user *will* be created in all repos. The
83 same is true of user deletion: that destructive action will
84 propagate through the group if you request it.
85
86 * **#5 and #1**: If you have a user “daisy” on both repos A and B in a
87 login group, logging in over the web to A doesn’t let you push
88 changes into B over SSH. Without the workaround linked above, SSH
89 only pays attention to the operating system’s user authentication
90 system, not Fossil’s.
91
92 Inversely, if Daisy successfully logs in over SSH to repo B, she
93 gains no access to any of the other repos in that group. She needs
94 at least one valid login over HTTP to one of the group’s repos.
95
96
97 ## Discussion
98
99 The end result of all of this is that you can have a subset of users
100 with credentials only on repo A, a different subset only on B, and a
101 third subset common to both. The only thing selecting which case applies
102 is restriction #1 above.
103
104 Login groups have names. A repo can be in only one of these named login
105 groups at a time.
106
107 Trust in login groups is transitive within a single server. Consider
108 this sequence:
109
110 ```
111 $ cd /path/to/A/checkout
112 $ fossil login-group join --name G ~/museum/B.fossil
113 $ cd /path/to/C/checkout
114 $ fossil login-group join ~/museum/B.fossil
115 ```
116
117 That creates login group G joining repo A to B, then joins C to B.
118 Although we didn’t explicitly tie C to A, a successful login on C gets
119 you into both A and B, within the restrictions set out above.
120
121 Changes are transitive in the same way, provided you check that “apply
122 to all” box on the user edit screen.
123
124 [lg]: /help?cmd=login-group
125 [sh]: ../server/any/http-over-ssh.md
126 [wo]: ./index.md#webonly
127
128 -----
129
130 *[Back to Administering User Capabilities](./)*
131

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button