API: deprecate toggle of superuser status in favor of new idempotent endpoint, update setup-all.sh

doc/release-notes/9887-new-superuser-status-endpoint.md

@@ -0,0 +1 @@
+The existing API endpoint for toggling the superuser status of a user has been deprecated in favor of a new API endpoint that allows you to explicitly and idempotently set the status as true or false. For details, see [the guides](https://dataverse-guide--10440.org.readthedocs.build/en/10440/api/native-api.html), #9887 and #10440.

doc/sphinx-guides/source/api/changelog.rst

@@ -7,6 +7,11 @@ This API changelog is experimental and we would love feedback on its usefulness.
     :local:
     :depth: 1
 
+v6.3
+----
+
+- **/api/admin/superuser/{identifier}**: The POST endpoint is being deprecated in favor for the PUT,which we can specifically set the superuser status in the body.
+
 v6.2
 ----
 

doc/sphinx-guides/source/api/native-api.rst

@@ -5306,13 +5306,35 @@ Example: ``curl -H "X-Dataverse-key: $API_TOKEN" -X POST  "https://demo.datavers
 
 This action changes the identifier of user johnsmith to jsmith.
 
-Make User a SuperUser
-~~~~~~~~~~~~~~~~~~~~~
+Toggle Superuser Status
+~~~~~~~~~~~~~~~~~~~~~~~
 
 Toggles superuser mode on the ``AuthenticatedUser`` whose ``identifier`` (without the ``@`` sign) is passed. ::
 
     POST http://$SERVER/api/admin/superuser/$identifier
 
+.. note:: This endpoint is deprecated. Use the set superuser status endpoint instead.
+
+.. _change-superuser-status:
+
+Set Superuser Status
+~~~~~~~~~~~~~~~~~~~~
+
+Specify the superuser status of a user with a boolean value.
+
+.. code-block:: bash
+
+  export SERVER_URL=http://localhost:8080
+  export USERNAME=jdoe
+  export IS_SUPERUSER=true
+  curl -X PUT "$SERVER/api/admin/superuser/$USERNAME" --data "$IS_SUPERUSER"
+
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -X PUT "http://localhost:8080/api/admin/superuser/jdoe" -d "true"
+
 .. _delete-a-user:
 
 Delete a User

src/main/java/edu/harvard/iq/dataverse/api/Admin.java

@@ -1030,20 +1030,39 @@ public Response deleteRole(@Context ContainerRequestContext crc, @PathParam("id"
     }
 
 	@Path("superuser/{identifier}")
+	@Deprecated
 	@POST
 	public Response toggleSuperuser(@PathParam("identifier") String identifier) {
 		ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "toggleSuperuser")
 				.setInfo(identifier);
 		try {
-			AuthenticatedUser user = authSvc.getAuthenticatedUser(identifier);
-                        if (user.isDeactivated()) {
-                            return error(Status.BAD_REQUEST, "You cannot make a deactivated user a superuser.");
-                        }
+			final AuthenticatedUser user = authSvc.getAuthenticatedUser(identifier);
+			return setSuperuserStatus(user, !user.isSuperuser());
+		} catch (Exception e) {
+			alr.setActionResult(ActionLogRecord.Result.InternalError);
+			alr.setInfo(alr.getInfo() + "// " + e.getMessage());
+			return error(Response.Status.INTERNAL_SERVER_ERROR, e.getMessage());
+		} finally {
+			actionLogSvc.log(alr);
+		}
+	}
 
-			user.setSuperuser(!user.isSuperuser());
+	private Response setSuperuserStatus(AuthenticatedUser user, Boolean isSuperuser) {
+		if (user.isDeactivated()) {
+			return error(Status.BAD_REQUEST, "You cannot make a deactivated user a superuser.");
+		}
+		user.setSuperuser(isSuperuser);
+		return ok("User " + user.getIdentifier() + " " + (user.isSuperuser() ? "set" : "removed")
+				+ " as a superuser.");
+	}
 
-			return ok("User " + user.getIdentifier() + " " + (user.isSuperuser() ? "set" : "removed")
-					+ " as a superuser.");
+	@Path("superuser/{identifier}")
+	@PUT
+	public Response setSuperuserStatus(@PathParam("identifier") String identifier, Boolean isSuperUser) {
+		ActionLogRecord alr = new ActionLogRecord(ActionLogRecord.ActionType.Admin, "changeSuperUserStatus")
+				.setInfo(identifier + ":" + isSuperUser);
+		try {
+            return setSuperuserStatus(authSvc.getAuthenticatedUser(identifier), isSuperUser);
 		} catch (Exception e) {
 			alr.setActionResult(ActionLogRecord.Result.InternalError);
 			alr.setInfo(alr.getInfo() + "// " + e.getMessage());

src/test/java/edu/harvard/iq/dataverse/api/AdminIT.java

@@ -21,7 +21,8 @@
 import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.BeforeAll;
-
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
 import java.util.Map;
 import java.util.UUID;
 import java.util.logging.Logger;
@@ -895,4 +896,15 @@ private String createTestNonSuperuserApiToken() {
         createUserResponse.then().assertThat().statusCode(OK.getStatusCode());
         return UtilIT.getApiTokenFromResponse(createUserResponse);
     }
+
+    @ParameterizedTest
+    @ValueSource(booleans={true,false})
+    public void testChangeSuperUserStatus(Boolean status) {
+        Response createUser = UtilIT.createRandomUser();
+        createUser.then().assertThat().statusCode(OK.getStatusCode());
+        String username = UtilIT.getUsernameFromResponse(createUser);
+        Response toggleSuperuser = UtilIT.changeSuperUserStatus(username, status);
+        toggleSuperuser.then().assertThat()
+                .statusCode(OK.getStatusCode());
+    }
 }

src/test/java/edu/harvard/iq/dataverse/api/RolesIT.java

@@ -18,7 +18,7 @@
  */
 public class RolesIT {
 
-    private static final Logger logger = Logger.getLogger(AdminIT.class.getCanonicalName());
+    private static final Logger logger = Logger.getLogger(RolesIT.class.getCanonicalName());
 
     @BeforeAll
     public static void setUp() {

src/test/java/edu/harvard/iq/dataverse/api/UtilIT.java

@@ -1525,6 +1525,11 @@ static Response makeSuperUser(String username) {
         return response;
     }
 
+    static Response changeSuperUserStatus(String username, Boolean isSuperUser) {
+        Response response = given().body(isSuperUser).put("/api/admin/superuser/" + username);
+        return response;
+    }
+
     static Response reindexDataset(String persistentId) {
         Response response = given()
                 .get("/api/admin/index/dataset?persistentId=" + persistentId);