Skip to content

Documentation
Documentation
Commit 48c7e912 by Tom Laudeman
Options

Change role to privilege, user type to role

parent dff9ca92
Showing with 99 additions and 99 deletions
Requirements/DBUser API.md
...@@ -18,9 +18,9 @@ For background about users, please see: ...@@ -18,9 +18,9 @@ For background about users, please see:
- support for data necessary to authenticate (log in), which is currently handled outside DBUser by - support for data necessary to authenticate (log in), which is currently handled outside DBUser by
OpenID. This data includes an access token and expires time OpenID. This data includes an access token and expires time
- support for user authorization for specific system features. This requirement relies on role(s). - support for user authorization for specific system features. This requirement relies on privilege(s).
- create user, requries a username which we default to the email address string. We also expect that the email - create user, requires a username which we default to the email address string. We also expect that the email
field will contain an email address. There was some discussion of multiple email addresses per user. That field will contain an email address. There was some discussion of multiple email addresses per user. That
has not been implemented. has not been implemented.
...@@ -29,15 +29,15 @@ For background about users, please see: ...@@ -29,15 +29,15 @@ For background about users, please see:
- delete or inactivate user - delete or inactivate user
- create role - create privilege
- add role to user - add privilege to user
- remove role from user - remove privilege from user
- delete role (probably inadvisable, but we make it possible) - delete privilege (probably inadvisable, but we make it possible)
- allow multiple roles per user - allow multiple privileges per user
- create session - create session
...@@ -61,7 +61,7 @@ using that account's username due to username being unique in table appuser. Use ...@@ -61,7 +61,7 @@ using that account's username due to username being unique in table appuser. Use
accidentally reused because the database creates them from a Postgres sequence. accidentally reused because the database creates them from a Postgres sequence.
Some features are described in more detail in other requirements docs although we list them below with Some features are described in more detail in other requirements docs although we list them below with
roles. Requirements here will cover data necessary to support implementation of authorization, and support privileges. Requirements here will cover data necessary to support implementation of authorization, and support
management of authorization. management of authorization.
Each user has account info: Each user has account info:
...@@ -88,17 +88,17 @@ Current session data includes: ...@@ -88,17 +88,17 @@ Current session data includes:
The REST API requires the same session data. REST API users will have the same Au/Az constraints 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 the DBUser API. Each user is granted one The system has privileges conceptually, extensively integrated throughout the DBUser API. Each user is granted one
or more roles. Each user has one or more roles, as many as necessary. or more privileges. Each user has one or more privileges, as many as necessary.
### Roles ### Privileges
The SNAC permission system is based entirely on roles (groups). SNAC is authorizing users to run various The SNAC permission system is based entirely on privileges (groups). SNAC is authorizing users to run various
functions. Ownership is a non-concept, but essentially the system owns all functions. In a situation like SNAC functions. Ownership is a non-concept, but essentially the system owns all functions. In a situation like SNAC
where there is a single owner, the concept of "owner" has no utility in authorization. The Linux concept of where there is a single owner, the concept of "owner" has no utility in authorization. The Linux concept of
"other" doesn't apply to SNAC as "other" is only allowed to perform read-only actions such as search. That "other" doesn't apply to SNAC as "other" is only allowed to perform read-only actions such as search. That
leaves SNAC needing only a role system. leaves SNAC needing only a privilege system.
(Optional paragraph) Not having "files", there is no concept of "file has no privileges" for user, group, or (Optional paragraph) Not having "files", there is no concept of "file has no privileges" for user, group, or
other. An example of what SNAC does not have is the shared web server situation where user grants privileges other. An example of what SNAC does not have is the shared web server situation where user grants privileges
...@@ -106,13 +106,13 @@ and group removes privileges. In a shared web server, users are all assigned to ...@@ -106,13 +106,13 @@ and group removes privileges. In a shared web server, users are all assigned to
accessible directories have no group permissions and are owned by group user. Lacking permissions for group 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 user, no one in group user has any access. Actual access then is granted only to the owner who has
read-write-execute (rwx) for that directory. Apache runs as suexec for each user, and thus each user's CGI read-write-execute (rwx) for that directory. Apache runs as suexec for each user, and thus each user's CGI
scripts gain access to only that user's directory via the user privs. scripts gain access to only that user's directory via the user privileges.
SNAC lacks the Linux "subtractive" permission which is sometimes used with groups permissions. Instead SNAC SNAC lacks the Linux "subtractive" permission which is sometimes used with groups permissions. Instead SNAC
has only additive permissions. has only additive permissions.
In a global sense, the cumulative collection of users and roles is complicated. However, that complexity is In a global sense, the cumulative collection of users and privileges is complicated. However, that complexity is
essential (not accidental) and on a per-user or per-role basis, things are very manageable. When managing the essential (not accidental) and on a per-user or per-privilege basis, things are very manageable. When managing the
system, imagine asking these typical, and manageable questions: system, imagine asking these typical, and manageable questions:
- List all users affiliated with California Digital Library (CDL). - List all users affiliated with California Digital Library (CDL).
...@@ -128,110 +128,110 @@ system, imagine asking these typical, and manageable questions: ...@@ -128,110 +128,110 @@ system, imagine asking these typical, and manageable questions:
- List all users who may run reports for their own affiliation. - List all users who may run reports for their own affiliation.
Below is an example. Anyone who can log in can get a dashboard, so there are no specific dashboard permissions Below is an example. Anyone who can log in can get a dashboard, so there are no specific dashboard permissions
(yet). The user id "public" and the role "research" may not make any sense. Conceptually, everyone has role (yet). The user id "public" and the privilege "research" may not make any sense. Conceptually, everyone has privilege
"Public HRT", so there's no reason to restrict or authorize it. In actual implementation the "what is public" "Public HRT", so there's no reason to restrict or authorize it. In actual implementation the "what is public"
divide is simply any published record or read-only actition on published constellations. The table below divide is simply any published record or read-only action on published constellations. The table below
initially had a user id "public" with role "Public HRT", and every user also had the role "Public HRT", but initially had a user id "public" with privilege "Public HRT", and every user also had the privilege "Public HRT", but
that was simply redundant. that was simply redundant.
The roles below are real, but do not imply any actual policy or any relation to persons living or dead. The privileges below are real, but do not imply any actual policy or any relation to persons living or dead.
Pulling a couple of random details from the table below, and wording them in English: Pulling a couple of random details from the table below, and wording them in English:
- Casey at CDL can approve NACO submissions (NACO approve) - Casey at CDL can approve NACO submissions (NACO approve)
- Jessie at NYPL is limited to assigning roles only for NYPL (affiliation-nypl and role-assign-own) - Jessie at NYPL is limited to assigning privileges only for NYPL (affiliation-nypl and privilege-assign-own)
| user | description | roles | | user | description | privileges |
|------------------|----------------|-------------------------------------------------------------------------------------------------| |------------------|----------------|-------------------------------------------------------------------------------------------------|
| Marley Turner | content expert | contribute, affiliation-none | | Marley Turner | content expert | contribute, affiliation-none |
| Remy Roberts | power editor | contribute, change-status-any, change owner, publish, affiliation-any | | 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, report-own-affiliation | | Casey Miyazaki | editor CDL | contribute, change-status-own, publish, NACO approve, affiliation-cdl, report-own-affiliation |
| Jessie Coughlin | admin NYPL | affiliation-nypl, enroll-own-affiliation report-own-affiliation, role-assign-own | | Jessie Coughlin | admin NYPL | affiliation-nypl, enroll-own-affiliation report-own-affiliation, privilege-assign-own |
| Avery Valenzuela | super admin | enroll-any, report-any, role-assign-any | | Avery Valenzuela | super admin | enroll-any, report-any, privilege-assign-any |
Roles have a number of traits. Privileges have a number of traits.
- Roles are additive, and all roles of a user define that user's authorized functions - Privileges are additive, and all privileges of a user define that user's authorized functions
- Roles are created and maintained by admins and developers. - Privileges are created and maintained by admins and developers.
- Some instance roles (such as affiliation) can be created by admins as needed. - Some instance privileges (such as affiliation) can be created by admins as needed.
- Roles (ideally) have a single privilege per role. Roles are very granular. - Privileges (ideally) have a single privilege per privilege. Privileges are very granular.
- Roles and privileges must be coordinated with work flows and application features. - Privileges and privileges must be coordinated with work flows and application features.
- One role exists per institutional affiliation. - One privilege exists per institutional affiliation.
- Every user has the conceptually role Public HRT, although no actual role exists for read-only access to published constellations - Every user has the conceptually privilege Public HRT, although no actual privilege exists for read-only access to published constellations
- Potentially, we can have roles for ad hoc groups (sub-institution, department, professional orgs, etc.) - Potentially, we can have privileges for ad hoc groups (sub-institution, department, professional orgs, etc.)
- Roles can be deprecated, but re-purposing roles is inadvisable from a security standpoint. - Privileges can be deprecated, but re-purposing privileges is inadvisable from a security standpoint.
- Roles need explicit, on-going policy guidance. - Privileges need explicit, on-going policy guidance.
The minimal role "Research" grants privileges for search history, and certain research reports. Members of The minimal privilege "Research" grants privileges for search history, and certain research reports. Members of
the public are mostly identical to Researchers. The primary feature gained by having an account is a the public are mostly identical to Researchers. The primary feature gained by having an account is a
persistent dashboard. As already noted, "Public HRT" not an actual role, but instead is conceptual. persistent dashboard. As already noted, "Public HRT" not an actual privilege, but instead is conceptual.
(Comment: I just noticed that roles are mostly verbs: research, contribute, delete, propose, approve, block, (Comment: I just noticed that privileges are mostly verbs: research, contribute, delete, propose, approve, block,
embargo, enrole, assign. It seems like a nice idea to enshrine this as a convention. We would have to change embargo, enroll, assign. It seems like a nice idea to enshrine this as a convention. We would have to change
"administrator" to "administer", and we need to come up with a verbs for the remaining roles, especially "administrator" to "administer", and we need to come up with a verbs for the remaining privileges, especially
"affiliation".) "affiliation".)
| Role | Role Description | | Privilege | Privilege Description |
|------------------------------+----------------------------------------------------------------------------| |----------------------------------+----------------------------------------------------------------------------|
| Research | Use discovery interface and dashboard, has an account | | Research | Use discovery interface and dashboard, has an account |
| Contribute | Create and edit constellations but cannot publish (contributor) | | Contribute | Create and edit constellations but cannot publish (contributor) |
| Publish | Approve constellation publication, change status to "published" (editor) | | Publish | Approve constellation publication, change status to "published" (editor) |
| Change status any | Change any status, removing locks, and so on, any affiliation | | Change status any | Change any status, removing locks, and so on, any affiliation |
| Change owner any | Change constellation user, changing which user has a lock, any affiliation | | Change owner any | Change constellation user, changing which user has a lock, any affiliation |
| Change status own | Change any status, removing locks, and so on, own affiliation only | | Change status own | Change any status, removing locks, and so on, own affiliation only |
| Change owner own | Change constellation user, changing user lock, own affiliation only | | Change owner own | Change constellation user, changing user lock, own affiliation only |
| Delete/embargo | Delete or embargo constellations (editor) | | Delete/embargo | Delete or embargo constellations (editor) |
| Propose delete/embargo | Propose delete or embargo | | Propose delete/embargo | Propose delete or embargo |
| Ontology propose | Propose headings in ontologies, but cannot approve headings | | Ontology propose | Propose headings in ontologies, but cannot approve headings |
| Ontology approve | Approve ontology headings (editor) | | Ontology approve | Approve ontology headings (editor) |
| Propose NACO | Create(?) NACO contributions, but not push(?) to NACO | | Propose NACO | Create(?) NACO contributions, but not push(?) to NACO |
| Approve NACO | Approve, finalize, submit NACO contributions (editor) | | Approve NACO | Approve, finalize, submit NACO contributions (editor) |
| Enroll | Enroll new SNAC participants, create new users | | Enroll | Enroll new SNAC participants, create new users |
| Role assign own institution | Assign new roles for own-institution users | | Privilege assign own institution | Assign new privileges for own-institution users |
| Role assign any institution | Assign new roles for any institution users | | Privilege assign any institution | Assign new privileges for any institution users |
| System administrator | Maintains server hardware and operating systems | | System administrator | Maintains server hardware and operating systems |
| Developer | Writes the SNAC application, a programmer | | Developer | Writes the SNAC application, a programmer |
| Web administrator | (duplicate? historical?) May perform admin tasks via the web interface | | Web administrator | (duplicate? historical?) May perform admin tasks via the web interface |
| Database administrator (DBA) | Create and maintain the SQL database | | Database administrator (DBA) | Create and maintain the SQL database |
| Block upload | Do bulk uploads of EAC-CPF, finding aids, etc. | | Block upload | Do bulk uploads of EAC-CPF, finding aids, etc. |
| Report own | Run own-institutional reports | | Report own | Run own-institutional reports |
| Report any | Run any report, super reporter | | Report any | Run any report, super reporter |
| Report admin | Run special administrative reports | | Report admin | Run special administrative reports |
| Affiliation X | Affiliated with institution X. | | Affiliation X | Affiliated with institution X. |
| Affiliation any | Affiliated with all institutions, a super role (discuss?) | | Affiliation any | Affiliated with all institutions, a super privilege (discuss?) |
Example user types, with their role(s) and description. Example role, with their privilege(s) and description.
| User type | Role(s) | User Description | | Role | Privilege(s) | User Description |
|----------------------------+-----------------------------------------------------+-------------------------------------------------------------| |----------------------------+--------------------------------------------------------------+---------------------------------------------------------------|
| Sysadmin | System administrator | Maintain server, backups, etc. | | Sysadmin | System administrator | Maintain server, backups, etc. |
| Database Administrator | DBA | Schema maintenance, data dumps, etc. | | Database Administrator | DBA | Schema maintenance, data dumps, etc. |
| Software engineer | Developer + DBA | Coding, testing, QA, release management, data loading, etc. | | Software engineer | Developer + DBA | Coding, testing, QA, release management, data loading, etc. |
| Manager | Enroll + Role assign own + Report own | SNAC accounts: create, manage, assign roles, run reports | | Manager | Enroll + Privilege assign own + Report own | SNAC accounts: create, manage, assign privileges, run reports |
| Peer vetting | Enroll | Approve moderators, reviewers, content experts | | Peer vetting | Enroll | Approve moderators, reviewers, content experts |
| Moderator | Publish | Approve maintenance changes, posting those changes | | Moderator | Publish | Approve maintenance changes, posting those changes |
| Reviewer/editor | Contribute + publish | Maintainer privileges, interacts with moderators | | Reviewer/editor | Contribute + publish | Maintainer privileges, interacts with moderators |
| Content expert | Contribute | Domain expert, may have zero institutional roles | | Content expert | Contribute | Domain expert, may have zero institutional privileges |
| Documentary editor | Contribute | (Any distinguishing roles?) | | Documentary editor | Contribute | (Any distinguishing privileges?) |
| Maintenance | Contribute, constellation | May be older terminology for "contribute" | | Maintenance | Contribute, constellation | May be older terminology for "contribute" |
| Research | Research | Use the discovery interface and history dashboard | | Research | Research | Use the discovery interface and history dashboard |
| Archival description donor | Block upload | May do bulk uploads of EAC-CPF, finding aids, etc. | | Archival description donor | Block upload | May do bulk uploads of EAC-CPF, finding aids, etc. |
| Name authority manager | Name authority | (superseded by Editor-NACO?) | | Name authority manager | Name authority | (superseded by Editor-NACO?) |
| Institutional admins | Report own | May run own-institutional reports | | Institutional admins | Report own | May run own-institutional reports |
| Public | n/a | No SNAC account, single session dashboard | | Public | n/a | No SNAC account, single session dashboard |
| Contributor | Contribute + Ontology propose | Creates/edit constellations, propose ontology headings | | Contributor | Contribute + Ontology propose | Creates/edit constellations, propose ontology headings |
| Author | Contribute + Publish + Propose Del/Emb+Propose NACO | Contribute, with additional privileges | | Author | Contribute + Publish + Propose Del/Emb+Propose NACO | Contribute, with additional privileges |
| Editor | Contribute + Publish + Delete/embargo + NACO | Review constellations, approve and publish | | Editor | Contribute + Publish + Delete/embargo + NACO | Review constellations, approve and publish |
| Author-NACO | Propose NACO | Creates NACO entries, sends to editor for submission | | Author-NACO | Propose NACO | Creates NACO entries, sends to editor for submission |
| Administrator | Contributor roles + Editor roles + enroll + assign | Everything, only own institution | | Administrator | Contributor privileges + Editor privileges + enroll + assign | Everything, only own institution |
| Administrator-super | Administrator roles + any institution | Admin plus assign roles for any user of any institution | | Administrator-super | Administrator privileges + any institution | Admin plus assign privileges for any user of any institution |
### API ### API
......
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