Skip to content

Documentation
Documentation
Commit 7b9b0700 by Tom Laudeman
Options

Improved prose for roles, more detail on user data, more examples

parent 8db4f154
Showing with 123 additions and 63 deletions
Requirements/DBUser API.md
...@@ -9,43 +9,112 @@ For background about users, please see: ...@@ -9,43 +9,112 @@ For background about users, please see:
[User Management Requirements](Requirements/User Management.md) [User Management Requirements](Requirements/User Management.md)
### What users must be able to ### What data and features must be provided
Users must be able to have a unique id, authenticate (login), and do various authorized functions. The list of - user must have a unique id
functions are in other requirements docs, and we will cover how people are granted authorized access, and how - user must be able to authenticate (login)
users and authorization are managed. - user msut be authorized for specific system features
Each user as account info, name, email, user id, password. Userid must be unique for all time, and thus, userids may not be reused. A unique userid internal to the
system may be a good idea. The textual user id such as "mst3k" or "mst3k@example.com" should probably also be
unique for all time, but (in theory) could be reused witn a new, unique system userid.
Each user as one or more roles, as many as necessary. Accounts need an active flag. Deleted accounts might be kept inactive, as an easy way to prevent accidentally
creating an account with the same name at some future time.
The list of features are described in more detail in other requirements docs although we list them below with
roles. Requirements here will cover implementation of authorization, and of management of authorization.
Each user has account info:
- id (not editable, database assigned record id)
- first name
- last name
- full name
- email which may be user id
- user id which may be email, should probably be unique
- avatar
- avatar small
- avatar large
- password, stored encrypted
Each user has one or more roles, as many as necessary.
When logged in, a user as a "session", and the session has some associated data. We anticipate that there When logged in, a user as a "session", and the session has some associated data. We anticipate that there
could be multiple simultaneous sessions per user, and each session needs its own unique data. Perhaps it is could be multiple simultaneous sessions per user, and each session needs its own unique data.
better to defer in depth discussion of session until user requirements and code are both functioning.
Current session data includes:
- access token from the authentication (OAuth?)
- expiration timestamp when the session will expire
The REST API requires the same session data. REST API users will have the same Au/Az constraints
The system has roles conceptually, extensively integrated throughout. Each user is granted one or more roles.
### Roles
The SNAC permission system is based entirely on roles (groups). SNAC is authorizing uses to run various
functions. Ownership is a non-concept, but essentially the system (sort of "root") owns all functions. When
there is only one owner, it has no use designing authorization partions. That leaves SNAC with a
role-only system.
In a global sense, the cumulative users and roles is complex. On a per-user or per-role basis, things are very
manageable. When managing the system, imagine asking these fairly constrained (manageable) questions:
- List all users affiliated with CDL.
- List all user affiliated with UC Irvine.
The REST API needs session as well. REST API users will have the same Au/Az strictures. - List all users who can enrole new users.
The system has roles conceptually extensively integrated throughout. Each user is granted roles in addition to - List all users who can publish constellations.
their base data.
#### Roles - List all users who may run reports for their own affiliation.
Roles are somewhat synonymous with Linux groups. Users have a primary group, but may have several groups. The Below is an example. Anyone who can login can get a dashboard, so there are no specific dashboard permissions
user has all privileges associated with each group of which they are a member. (yet). The userid public and the role "researcher" may not any sense. Everyone has it, so there's no reason to
mention/restrict/authorize it. This table initially had a userid "public" with role "Public HRT", and every
user also had the role "Public HRT", but that is simply redundant. When it comes to implementation, the
authorization system will actually use some convention for testing role. The feature "Public HRT" can call a
role test that always returns true.
The roles below are real, but do not imply any actual policy or any relation to persons living or dead.
Pulling some random details, and wording them in English, the table below says that Casey at CDL can approve
NACO submissions (NACO approve). Jessy at NYPL is limited to assigning roles only for NYPL (affiliation-nypl
and role-assign-own).
| user | description | roles |
|------------------+----------------+-------------------------------------------------------------------------------------------------|
| Marley Turner | content expert | contribute, affiliation-none |
| Remy Roberts | power editor | contribute, change-status-any, change owner, publish, affiliation-any |
| Casey Miyazaki | editor CDL | contribute, change-status-own, publish, NACO approve, affiliation-cdl, reporter-own-affiliation |
| Jessie Coughlin | admin NYPL | affiliation-nypl, enroll-own-affiliation reporter-own-affiliation, role-assign-own |
| Avery Valenzuela | super admin | enroll-any, reporter-any, role-assign-any |
Not having "files", there is no concept of "file has no privs" for user, group, or other. An example of what
SNAC does not have is the shared web server situation. In a shared web server, users are all assigned to a
group "users". Web accessible directories have no group permissions and are owned by group user. Lacking
permissions for group user, no one in group user has any access. Actual access then is granted only to the
owner who has rwx for that directory. Apache runs as suexec for each user, and thus each users CGI scripts
gain access to only that user's directory via the user privs.
SNAC lacks this "subtractive" permission, and instead has only additive permissions.
Roles have a number of traits: Roles have a number of traits:
- Created and maintained by admins with role-granting privileges - Created and maintained by admins with role-granting privileges
- There is (ideally) a single privilege per role - There is (ideally) a single privilege per role
- Roles and privileges must be coordinated with workflows and application features - Roles and privileges must be coordinated with workflows and application features
- At least one role exists per institution - At least one role exists per institutional affiliation
- At least one role per user, Public aka History Research Tool (HRT) user - Every user has the implied role Public HRT
- Potentially we can have roles for ad-hoc groups (sub-institution, department, professional orgs, etc.) - Potentially we can have roles for ad-hoc groups (sub-institution, department, professional orgs, etc.)
- Can be deprecated, but it repurposing roles is inadvisable from a security standpoint - Roles can be deprecated, but it repurposing roles is inadvisable from a security standpoint
- Need explicit, on-going policy guidance - Need explicit, on-going policy guidance
Unlike Linux where every file and directory is "owned" by a user and group, SNAC constellations have no
ownership.
Every account will have the "Researcher" role which has the same privileges as the general public, but with a Every account will have the "Researcher" role which has the same privileges as the general public, but with a
TBD set of basic privileges including: search history, certain researcher reports. An account is not necessary TBD set of basic privileges including: search history, certain researcher reports. An account is not necessary
...@@ -53,31 +122,37 @@ to use SNAC. Members of the public are mostly identical to Researchers. The prim ...@@ -53,31 +122,37 @@ to use SNAC. Members of the public are mostly identical to Researchers. The prim
an account is a persistent dashboard. an account is a persistent dashboard.
| Role | Role Description | | Role | Role Description |
|-------------------------------+------------------------------------------------------------------------| |-------------------------------+---------------------------------------------------------------------------|
| Public HRT | No account, but may use HRT public interfaces to SNAC | | Public HRT | No account, but may use HRT public interfaces to SNAC |
| Researcher | May use the discovery interface and history dashboard, has an account | | Researcher | May use the discovery interface and history dashboard, has an account |
| Create/edit | Create and edit constellations but cannot publish (contributor) | | Contribute | Create and edit constellations but cannot publish (contributor) |
| Publish | May approve constellation publication (editor) | | Publish | Approve constellation publication (editor) |
| Delete/embargo | May delete or embargo constellations (editor) | | Change status any | Change status, removing locks, and so on, any affiliation |
| Propose delete/embargo | May propose delete or embargo | | Change owner any | Change constellation user, changing which user has a lock, any affilation |
| Ontology propose | May propose headings in ontologies, but cannot approve headings | | Change status own | Change status, removing locks, and so on, own affiliation only |
| Ontology approve | May approve ontology headings (editor) | | Change owner own | Change constellation user, changing user lock, own affiliation only |
| Propose NACO | May create(?) NACO contributions, but not push(?) to NACO | | Delete/embargo | Delete or embargo constellations (editor) |
| NACO approve/finalize/submit | May approve NACO contributions (editor) | | Propose delete/embargo | Propose delete or embargo |
| Enroll | May enroll new SNAC participants, create new users | | Ontology propose | Propose headings in ontologies, but cannot approve headings |
| Role assign own institution | May assign new roles for own-institution users | | Ontology approve | Approve ontology headings (editor) |
| Role assign any institution | May assign new roles for any institution users | | Propose NACO | Create(?) NACO contributions, but not push(?) to NACO |
| System administrator | Maintains server hardware and operating systems | | NACO approve/finalize/submit | Appprove NACO contributions (editor) |
| Developer | Writes the SNAC application, a programmer | | Enroll | Enroll new SNAC participants, create new users |
| Web administrator | (duplicate? historical?) May perform admin tasks via the web interface | | Role assign own institution | Assign new roles for own-institution users |
| Database administrator | Create and maintain the SQL database | | Role assign any institution | Assign new roles for any institution users |
| Block upload | May do bulk uploads of EAC-CPF, finding aids, etc. | | System administrator | Maintains server hardware and operating systems |
| Institutional reporter | May run own-institutional reports | | Developer | Writes the SNAC application, a programmer |
| Super reporter | May run any report | | Web administrator | (duplicate? historical?) May perform admin tasks via the web interface |
| Instutional affiliation X | Affiliated with institution X. | | Database administrator | Create and maintain the SQL database |
| Instutional affiliation super | Affiliated with all instutions, a super role (discuss?) | | Block upload | Do bulk uploads of EAC-CPF, finding aids, etc. |
| Institutional reporter | Run own-institutional reports |
| Super reporter | Run any report |
| Instutional affiliation X | Affiliated with institution X. |
| Instutional affiliation super | Affiliated with all instutions, a super role (discuss?) |
More example user types, with their role(s) and description.
| User type | Role(s) | User Description | | User type | Role(s) | User Description |
...@@ -97,29 +172,14 @@ an account is a persistent dashboard. ...@@ -97,29 +172,14 @@ an account is a persistent dashboard.
| Name authority manager | Name authority | (superceded by Editor-NACO?) | | Name authority manager | Name authority | (superceded by Editor-NACO?) |
| Institutional admins | Institutional reporter | May run own-institutional reports | | Institutional admins | Institutional reporter | May run own-institutional reports |
| Public | Public | No SNAC account, single session dashboard | | Public | Public | No SNAC account, single session dashboard |
| Contributor | Create/edit + Ontology propose | Creates/edit constellations, propose ontology headings | | Contributor | Contribute + Ontology propose | Creates/edit constellations, propose ontology headings |
| Author | Create/edit + Publish + Propose Del/Emb+Propose NACO | A contributor, with additional privileges | | Author | Contribute + Publish + Propose Del/Emb+Propose NACO | A contributor, with additional privileges |
| Editor | Create/edit + Publish + Delete/embargo + NACO | Review constellations, approve and publish | | Editor | Contribute + Publish + Delete/embargo + NACO | Review constellations, approve and publish |
| Author-NACO | Create provisional NACO | Creates NACO entries, sends to editor for submission | | Author-NACO | Create provisional NACO | Creates NACO entries, sends to editor for submission |
| Administrator | Author + editor + enroll + assign | Everything, only own institution | | Administrator | Author + editor + enroll + assign | Everything, only own institution |
| Administrator-super | Administrator + any institution | Admin plus assign roles for any user of any institution | | Administrator-super | Administrator + any institution | Admin plus assign roles for any user of any institution |
### What data has to be stored for the user
Accounts need an active flag. Deleted accounts might be kept inactive, in order to prevent accidentally
creating an account wiht the same name at some future time.
### What data is bookkeeping
### Authentication login
### Authorization privileges
### Web Session and user interface
- Users
- Dashboard tabs
- Historical Research Tool per-user search history
- Maintenance tool per-user workflow task status
- Notifications, all users
Requirements/User Management.md
...@@ -69,7 +69,7 @@ See the two tables "Role" and "User type" in the "DBUser API" documentation: ...@@ -69,7 +69,7 @@ See the two tables "Role" and "User type" in the "DBUser API" documentation:
[Role in Database User API](Requirements/DBUser API.md#roles) [Role in Database User API](Requirements/DBUser API.md#roles)
Remember: institutional affiliation roles aren't all listed in the tables. There will be one institutional Remember: institutional affiliation roles aren't all listed in the tables. There will be one institutional
affiliation roles per institution. Users may have zero, one, or several institutional roles that define affiliation role per institution. Users may have zero, one, or several institutional roles that define
insitutions with which the user is affiliated. insitutions with which the user is affiliated.
It is possible for an institutional administrator to also be a member of more than one It is possible for an institutional administrator to also be a member of more than one
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment