-
Notifications
You must be signed in to change notification settings - Fork 57
User administration how to
Written 2023-06 for a specific use-case, deemed useful enough to share but insufficiently authoratitive for catmaid.org
Instances managed by the catmaid org tend to be protected by CATMAID's own authentication, and HTTP basic authentication.
In a couple of situations, admins need to set passwords. By preference, have the user type in their password at the admin's keyboard during the process. Otherwise, randomly generate a password and send it to them over a separate (ideally personal, encrypted) channel so that it does not appear alongside any context of where it's used.
We use htpasswd to maintain a user database as a file. In nginx, you can restrict access to particular locations to users in this database by adding this to your location block:
auth_basic "Restricted";
auth_basic_user_file /path/to/db;
Add a user to the database with sudo htpasswd /path/to/db new_user.
Delete a user with the -D switch.
These passwords are set by the admin of the host server; NOT by the admin of the CATMAID instance. Users cannot change this password, so use a human-memorable random generator like correcthorsebatterystaple. These passwords are transmitted in plain text (base64-encoded) - users should be reminded that while they technically shouldn't duplicate passwords in general, they really, really shouldn't here.
This is managed through the CATMAID administrative interface (https://$YOURINSTANCE/admin), by any user with Staff status and sufficient permissions.
By default, a group is created whenever a new user is created, which shares their username (like in *nix). Groups generally have two purposes.
- Manage project permissions for multiple users at once (more on this later)
- Controlling which users can edit each others' annotations
If experienced reconstructor alice is training novice bob, then alice should be added to the group bob (automatically created when bob's user was created) so that she can edit his work.
When manually creating a group, ignore the "Permissions" block.
Go to Users -> Add user, set the username (easily identifiable makes it much easier to administrate) and password. Users should change this password as soon as they log in; encourage them to do so by making the temporary password very difficult to remember and type (e.g. a long random alphanumeric string with mixed cases and punctuation). Click "Save and continue editing".
The user has now been created, but it's useful to fill in more information (this is the normal user editing page). Add the first name, and last name, and email address where indicated.
If they need to access the admin interface (for managing users, projects, stacks etc), check "Staff status"; if they are to be given all permissions, check "Superuser status". Add them to any necessary groups.
Ensure that a user is added to the group which shares their name, and that that is set to their primary group.
Ensure also that "Show tracing tool" is checked (probably the default, according to the instance's settings.py.
Ignore the "User permissions" block.
Go to Projects -> $YOURPROJECT -> Object permissions (top right). This is a more ergonomic way of managing permissions on a per-project basis than instance-wide permissions set directly on the group or user.
Object permissions can be set for users or for groups. It is convenient to use groups here: this way, new users need only be added to the correct group.
The important permissions for most users are "can browse projects" (i.e. see annotations), "can annotate projects" (i.e. add reconstructions of their own), and "can annotate project using API token". This last is split out because software with a simple bug to do a lot more damage more quickly than a human with an errant mouse. "browse" is enough for users to fetch data through the API.
It is recommended to create groups with a naming scheme like $YOURPROJECT-browser, $YOURPROJECT-annotator, and $YOURPROJECT-api, set the correct object permissions for that project, and then add users to the groups as necessary.