From 1f4842644330c9aeedf426883257929027b28ec7 Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Thu, 4 Feb 2021 23:53:48 -0500 Subject: [PATCH 1/8] docs for disable/delete/anon, need to move to user admin section --- doc/sphinx-guides/source/api/native-api.rst | 67 ++++++++++++++++++++- 1 file changed, 66 insertions(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 44d099a1685..36b3193cdb4 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -2961,6 +2961,8 @@ Example: ``curl -H "X-Dataverse-key: $API_TOKEN" -X POST http://demo.dataverse.o This action moves account data from jsmith2 into the account jsmith and deletes the account of jsmith2. +Note: User accounts can only be merged if they are either both enabled or both disabled. See :ref:`disable a user`. + .. _change-identifier-label: Change User Identifier @@ -2992,9 +2994,60 @@ Deletes an ``AuthenticatedUser`` whose ``id`` is passed. :: DELETE http://$SERVER/api/admin/authenticatedUsers/id/$id -Note: If the user has performed certain actions such as creating or contributing to a Dataset or downloading a file they cannot be deleted. +Note: If the user has performed certain actions such as creating or contributing to a Dataset or downloading a file they cannot be deleted. If a user cannot be deleted due to performing certain actions, you can choose to :ref:`disable a user`. +.. _disable-a-user: + +Disable a User +~~~~~~~~~~~~~~ + +Disables an ``AuthenticatedUser`` whose ``identifier`` (without the ``@`` sign) is passed. :: + + PUT http://$SERVER/api/admin/authenticatedUsers/disable/$identifier + +Disables an ``AuthenticatedUser`` whose ``id`` is passed. :: + + PUT http://$SERVER/api/admin/authenticatedUsers/disable/id/$id +Note: Since the primary purpose of Dataverse is to serve as an archive and to track data accesses and the modifications of data and metadata, a simple mechanism to delete users that have performed certain actions in the system is not provided by design. + +Disabling a user with this endpoint will: + +- Disable the user's ability to log in to the Dataverse installation +- Remove the user's access from all datasets and files +- Cancel any pending file access requests generated by the user +- Remove the user from all groups +- No longer have notifications generated or sent by the Dataverse installation + +Disabling a user with this endpoint will keep: + +- The user's contributions to datasets, including dataset creation, file uploads, publishing, submitting for review, and returning to author. +- Any Dataverse Collections where the user is the sole administrator +- The user's access to datafiles in the Dataverse installation, including guestbook records and acceptance of terms of use. +- The user's account information (specifically name, email, affiliation, and position) + +If it is determined that disabling a user is not sufficient, it is possible anonymize a user through use of the :ref:`merge-accounts-label` feature. See :ref:`Anonymize a User ` for more information about this process. + +.. _anonymize-a-user: + +Anonymize a User +~~~~~~~~~~~~~~~~ + +In some cases, due to privacy laws or other organizational policies, it may be required to anonymize a user. This process should only be used in cases where a Dataverse installation has the need to completely remove the traces of a user from the Dataverse installation. This process is only provided because it is not feasible for the Dataverse Software to provide deletion and deactivation options that will satisfy all use cases and all privacy laws, so the most complete deletion option is provided here. + +Note: Before going through these steps, please note that you will be permanently losing: + +- The user's contributions to datasets, including dataset creation, file uploads, publishing, submitting for review, and returning to author. This will all be marked as "Anonymous User" in your Dataverse installation, and it will not be possible to track who made changes as part of the archival record. +- Records of the user's access to datafiles in the Dataverse installation, including guestbook records and acceptance of terms of use. This could potentially introduce issues where it is no longer possible for data curators and owners to follow up with those who have accessed data on the application, which may be a legal requirement or data sharing agreement. It will be up to the Dataverse installation administrators to determine which datasets the user has accessed to determine if anonymization is feasible in these situations. +- The user's account information (specifically name, email, affiliation, and position). This will make it impossible to follow up with the user being deleted. You may find that you need to contact a user about a security breach or something else in the future, and you will not able to do so. + +To anonymize a user in your Dataverse installation: + +- Create a user called "Anonymous User" +- Use the :ref:`merge-accounts-label` functionality to merge the user you wish to anonymize INTO the Anonymous User +- Remove All Roles from the Anonymous User, either through the Dashboard or the :ref:`Remove Role Assignments ` API. + +Once you've created the Anonymous User once, you will not need to create it again. List Role Assignments of a Role Assignee ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3005,6 +3058,18 @@ List all role assignments of a role assignee (i.e. a user or a group):: Note that ``identifier`` can contain slashes (e.g. ``&ip/localhost-users``). +.. _remove-role-assignments: + +Remove Role Assignments of Role Assignee +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Delete all role assignments of a role assignee (i.e. a user or a group):: + + DELETE http://$SERVER/api/admin/assignments/assignees/$identifier + +Note that ``identifier`` can contain slashes (e.g. ``&ip/-users``). + + List Permissions a User Has on a Dataverse Collection or Dataset ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 2af33fd9662328d86518c6f8c985c187398d1a0b Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Fri, 5 Feb 2021 15:04:20 -0500 Subject: [PATCH 2/8] draft code review feedback --- doc/sphinx-guides/source/api/native-api.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 36b3193cdb4..1d00ea80206 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -2994,7 +2994,7 @@ Deletes an ``AuthenticatedUser`` whose ``id`` is passed. :: DELETE http://$SERVER/api/admin/authenticatedUsers/id/$id -Note: If the user has performed certain actions such as creating or contributing to a Dataset or downloading a file they cannot be deleted. If a user cannot be deleted due to performing certain actions, you can choose to :ref:`disable a user`. +Note: If the user has performed certain actions such as creating or contributing to a Dataset or downloading a file they cannot be deleted. If a user cannot be deleted for this reason, you can choose to :ref:`disable a user`. .. _disable-a-user: @@ -3022,7 +3022,6 @@ Disabling a user with this endpoint will: Disabling a user with this endpoint will keep: - The user's contributions to datasets, including dataset creation, file uploads, publishing, submitting for review, and returning to author. -- Any Dataverse Collections where the user is the sole administrator - The user's access to datafiles in the Dataverse installation, including guestbook records and acceptance of terms of use. - The user's account information (specifically name, email, affiliation, and position) @@ -3037,15 +3036,18 @@ In some cases, due to privacy laws or other organizational policies, it may be r Note: Before going through these steps, please note that you will be permanently losing: -- The user's contributions to datasets, including dataset creation, file uploads, publishing, submitting for review, and returning to author. This will all be marked as "Anonymous User" in your Dataverse installation, and it will not be possible to track who made changes as part of the archival record. -- Records of the user's access to datafiles in the Dataverse installation, including guestbook records and acceptance of terms of use. This could potentially introduce issues where it is no longer possible for data curators and owners to follow up with those who have accessed data on the application, which may be a legal requirement or data sharing agreement. It will be up to the Dataverse installation administrators to determine which datasets the user has accessed to determine if anonymization is feasible in these situations. +- The user's contributions to datasets, including dataset creation, file uploads, publishing, submitting for review, and returning to author. This will all be marked as "Anonymous User" in your Dataverse installation, and it will not be possible to track who made changes as part of the archival record. - The user's account information (specifically name, email, affiliation, and position). This will make it impossible to follow up with the user being deleted. You may find that you need to contact a user about a security breach or something else in the future, and you will not able to do so. +You will not lose: + +- Email, First Name, and Last Name in Guestbook records. + To anonymize a user in your Dataverse installation: -- Create a user called "Anonymous User" +- Create a user called "Anonymous User". This is a one-time step. - Use the :ref:`merge-accounts-label` functionality to merge the user you wish to anonymize INTO the Anonymous User -- Remove All Roles from the Anonymous User, either through the Dashboard or the :ref:`Remove Role Assignments ` API. +- Disable the user using the :ref:`disable a user` API. Once you've created the Anonymous User once, you will not need to create it again. From ecaaa9bda382951eb6e4a62a81d0aac575fc6a8c Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Fri, 5 Feb 2021 16:06:15 -0500 Subject: [PATCH 3/8] removing anon and documentation for remove roles API --- doc/sphinx-guides/source/api/native-api.rst | 42 ++------------------- 1 file changed, 3 insertions(+), 39 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 1d00ea80206..43b9e668cb6 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -3014,43 +3014,19 @@ Note: Since the primary purpose of Dataverse is to serve as an archive and to tr Disabling a user with this endpoint will: - Disable the user's ability to log in to the Dataverse installation -- Remove the user's access from all datasets and files +- Remove the user's access from all Dataverse collections, datasets and files - Cancel any pending file access requests generated by the user - Remove the user from all groups - No longer have notifications generated or sent by the Dataverse installation Disabling a user with this endpoint will keep: -- The user's contributions to datasets, including dataset creation, file uploads, publishing, submitting for review, and returning to author. -- The user's access to datafiles in the Dataverse installation, including guestbook records and acceptance of terms of use. +- The user's contributions to datasets, including dataset creation, file uploads, and publishing. +- The user's access history to datafiles in the Dataverse installation, including guestbook records and acceptance of terms of use. - The user's account information (specifically name, email, affiliation, and position) If it is determined that disabling a user is not sufficient, it is possible anonymize a user through use of the :ref:`merge-accounts-label` feature. See :ref:`Anonymize a User ` for more information about this process. -.. _anonymize-a-user: - -Anonymize a User -~~~~~~~~~~~~~~~~ - -In some cases, due to privacy laws or other organizational policies, it may be required to anonymize a user. This process should only be used in cases where a Dataverse installation has the need to completely remove the traces of a user from the Dataverse installation. This process is only provided because it is not feasible for the Dataverse Software to provide deletion and deactivation options that will satisfy all use cases and all privacy laws, so the most complete deletion option is provided here. - -Note: Before going through these steps, please note that you will be permanently losing: - -- The user's contributions to datasets, including dataset creation, file uploads, publishing, submitting for review, and returning to author. This will all be marked as "Anonymous User" in your Dataverse installation, and it will not be possible to track who made changes as part of the archival record. -- The user's account information (specifically name, email, affiliation, and position). This will make it impossible to follow up with the user being deleted. You may find that you need to contact a user about a security breach or something else in the future, and you will not able to do so. - -You will not lose: - -- Email, First Name, and Last Name in Guestbook records. - -To anonymize a user in your Dataverse installation: - -- Create a user called "Anonymous User". This is a one-time step. -- Use the :ref:`merge-accounts-label` functionality to merge the user you wish to anonymize INTO the Anonymous User -- Disable the user using the :ref:`disable a user` API. - -Once you've created the Anonymous User once, you will not need to create it again. - List Role Assignments of a Role Assignee ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -3060,18 +3036,6 @@ List all role assignments of a role assignee (i.e. a user or a group):: Note that ``identifier`` can contain slashes (e.g. ``&ip/localhost-users``). -.. _remove-role-assignments: - -Remove Role Assignments of Role Assignee -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Delete all role assignments of a role assignee (i.e. a user or a group):: - - DELETE http://$SERVER/api/admin/assignments/assignees/$identifier - -Note that ``identifier`` can contain slashes (e.g. ``&ip/-users``). - - List Permissions a User Has on a Dataverse Collection or Dataset ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From eafdc73ecde663d04f6790b19bb5be57b8883932 Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Tue, 9 Feb 2021 22:16:44 -0500 Subject: [PATCH 4/8] updates from draft code review --- doc/sphinx-guides/source/api/native-api.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 43b9e668cb6..ee606ea94bd 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -3009,7 +3009,7 @@ Disables an ``AuthenticatedUser`` whose ``id`` is passed. :: PUT http://$SERVER/api/admin/authenticatedUsers/disable/id/$id -Note: Since the primary purpose of Dataverse is to serve as an archive and to track data accesses and the modifications of data and metadata, a simple mechanism to delete users that have performed certain actions in the system is not provided by design. +Note: A primary purpose of most Dataverse installations is to serve an archive. In the archival space, there are best practices around the tracking of data access and the tracking of modifications to data and metadata. In support of these key workflows, a simple mechanism to delete users that have performed edit or access actions in the system is not provided. Providing a Disable User endpoint instead of a Delete User endpoint is by design. Disabling a user with this endpoint will: @@ -3022,11 +3022,9 @@ Disabling a user with this endpoint will: Disabling a user with this endpoint will keep: - The user's contributions to datasets, including dataset creation, file uploads, and publishing. -- The user's access history to datafiles in the Dataverse installation, including guestbook records and acceptance of terms of use. +- The user's access history to datafiles in the Dataverse installation, including guestbook records. - The user's account information (specifically name, email, affiliation, and position) -If it is determined that disabling a user is not sufficient, it is possible anonymize a user through use of the :ref:`merge-accounts-label` feature. See :ref:`Anonymize a User ` for more information about this process. - List Role Assignments of a Role Assignee ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From a3b51d729f12e111b20a0a6928204a6e85ccaab1 Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Tue, 9 Feb 2021 22:30:56 -0500 Subject: [PATCH 5/8] adding links from user administration --- doc/sphinx-guides/source/admin/user-administration.rst | 10 ++++++++++ doc/sphinx-guides/source/api/native-api.rst | 4 +++- 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/admin/user-administration.rst b/doc/sphinx-guides/source/admin/user-administration.rst index bc9be64775f..2999c6e0856 100644 --- a/doc/sphinx-guides/source/admin/user-administration.rst +++ b/doc/sphinx-guides/source/admin/user-administration.rst @@ -44,6 +44,16 @@ Change User Identifier See :ref:`change-identifier-label` +Delete a User +------------- + +See :ref:`delete-a-user` + +Disable a User +-------------- + +See :ref:`disable-a-user` + Confirm Email ------------- diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index ee606ea94bd..312175d4c74 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -2982,7 +2982,9 @@ Make User a SuperUser Toggles superuser mode on the ``AuthenticatedUser`` whose ``identifier`` (without the ``@`` sign) is passed. :: POST http://$SERVER/api/admin/superuser/$identifier - + +.. _delete-a-user: + Delete a User ~~~~~~~~~~~~~ From c85691bc19fc88b5f1df2d46b63d121bfa1dc16e Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Thu, 11 Feb 2021 09:59:20 -0500 Subject: [PATCH 6/8] updates from more review --- doc/sphinx-guides/source/api/native-api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 312175d4c74..a05bc8d81c1 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -3011,12 +3011,13 @@ Disables an ``AuthenticatedUser`` whose ``id`` is passed. :: PUT http://$SERVER/api/admin/authenticatedUsers/disable/id/$id -Note: A primary purpose of most Dataverse installations is to serve an archive. In the archival space, there are best practices around the tracking of data access and the tracking of modifications to data and metadata. In support of these key workflows, a simple mechanism to delete users that have performed edit or access actions in the system is not provided. Providing a Disable User endpoint instead of a Delete User endpoint is by design. +Note: A primary purpose of most Dataverse installations is to serve an archive. In the archival space, there are best practices around the tracking of data access and the tracking of modifications to data and metadata. In support of these key workflows, a simple mechanism to delete users that have performed edit or access actions in the system is not provided. Providing a Disable User endpoint for users who have taken certain actions in the system alongside a Delete User endpoint to remove users that haven't taken certain actions in the system is by design. Disabling a user with this endpoint will: - Disable the user's ability to log in to the Dataverse installation - Remove the user's access from all Dataverse collections, datasets and files +- Prevent a user from being assigned any roles - Cancel any pending file access requests generated by the user - Remove the user from all groups - No longer have notifications generated or sent by the Dataverse installation From bb03310dd388beebbc762f1f780fac3c50cdb935 Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Wed, 17 Feb 2021 12:40:52 -0500 Subject: [PATCH 7/8] Update native-api.rst --- doc/sphinx-guides/source/api/native-api.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index a05bc8d81c1..2146060ef37 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -3013,9 +3013,11 @@ Disables an ``AuthenticatedUser`` whose ``id`` is passed. :: Note: A primary purpose of most Dataverse installations is to serve an archive. In the archival space, there are best practices around the tracking of data access and the tracking of modifications to data and metadata. In support of these key workflows, a simple mechanism to delete users that have performed edit or access actions in the system is not provided. Providing a Disable User endpoint for users who have taken certain actions in the system alongside a Delete User endpoint to remove users that haven't taken certain actions in the system is by design. +This is an irreversible action. There is no option to undisable a user. + Disabling a user with this endpoint will: -- Disable the user's ability to log in to the Dataverse installation +- Disable the user's ability to log in to the Dataverse installation. A message will be shown, stating that the account has been disabled. - Remove the user's access from all Dataverse collections, datasets and files - Prevent a user from being assigned any roles - Cancel any pending file access requests generated by the user From e9845c077ef847e7bb57feb95c67ef7859519389 Mon Sep 17 00:00:00 2001 From: Danny Brooke Date: Thu, 18 Feb 2021 12:31:41 -0500 Subject: [PATCH 8/8] Update native-api.rst --- doc/sphinx-guides/source/api/native-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/api/native-api.rst b/doc/sphinx-guides/source/api/native-api.rst index 2146060ef37..6d7b200f11a 100644 --- a/doc/sphinx-guides/source/api/native-api.rst +++ b/doc/sphinx-guides/source/api/native-api.rst @@ -3017,7 +3017,7 @@ This is an irreversible action. There is no option to undisable a user. Disabling a user with this endpoint will: -- Disable the user's ability to log in to the Dataverse installation. A message will be shown, stating that the account has been disabled. +- Disable the user's ability to log in to the Dataverse installation. A message will be shown, stating that the account has been disabled. The user will not able to create a new account with the same email address, ORCID, Shibboleth, or other login type. - Remove the user's access from all Dataverse collections, datasets and files - Prevent a user from being assigned any roles - Cancel any pending file access requests generated by the user