Merge pull request #66 from ScotGovAnalysis/workgroup-2fa

Add workgroup_mandate_2fa

Author: alice-hannah

NAMESPACE

@@ -24,6 +24,7 @@ export(upload_file)
 export(upload_file_version)
 export(versions)
 export(workgroup_bypass_2fa)
+export(workgroup_mandate_2fa)
 export(workspaces)
 export(write_data)
 export(write_data_version)

NEWS.md

@@ -23,6 +23,9 @@ to view status (`mobile_auth_staus()`) and to login (`mobile_auth_login()`)
 The `type` argument now only accepts an empty list (default to return all asset 
 types) or a list of length 1.
 
+* New `workgroup_mandate_2fa()` provides ability to enable or disable mandatory 
+two-factor authentication (2FA) in workgroups (#65).
+
 # objr 0.1.1
 
 * Set minimum versions for `dplyr` and `tidyr` dependencies (#32).

R/bypass_2fa.R

@@ -86,3 +86,46 @@ participant_bypass_2fa <- function(participant_uuid,
   invisible(response)
 
 }
+
+
+#' Enable/disable mandatory two-factor authentication for workgroup
+#'
+#' @details
+#' More information on two-factor authentication can be found in
+#' `vignette("two-factor")`.
+#'
+#' More details on this endpoint are available in the
+# nolint start: line_length_linter
+#' \href{https://secure.objectiveconnect.co.uk/publicapi/1/swagger-ui/index.html#/Workgroups/setTwoStepMandatory}{API documentation}.
+# nolint end
+#'
+#' @param workgroup_uuid Workgroup UUID
+#' @param mandate Logical to indicate whether two-factor authentication should
+#' be mandatory in the workgroup
+#' @inheritParams objr
+#'
+#' @return API response (invisibly)
+#'
+#' @export
+
+workgroup_mandate_2fa <- function(workgroup_uuid,
+                                  mandate = TRUE,
+                                  use_proxy = FALSE) {
+
+  response <- objr(
+    endpoint = "workgroups",
+    url_path = list(workgroup_uuid, "twostepmandatory"),
+    method = "PUT",
+    body = list(twoStepMandatory = tolower(mandate)),
+    use_proxy = use_proxy
+  )
+
+  if (httr2::resp_status(response) == 204) {
+    cli::cli_alert_success(
+      "Mandatory 2FA setting successfully updated for workgroup."
+    )
+  }
+
+  invisible(response)
+
+}

_pkgdown.yml

@@ -1,4 +1,4 @@
-url: https://scotgovanalysis.github.io/objr
+url: https://ScotGovAnalysis.github.io/objr
 
 development:
   mode: auto
@@ -96,6 +96,7 @@ reference:
 - subtitle: Two-factor authentication
   desc: See `vignette("two-factor")` for more information.
   contents:
+  - workgroup_mandate_2fa
   - workgroup_bypass_2fa
   - participant_bypass_2fa
 

man/workgroup_mandate_2fa.Rd

@@ -0,0 +1,11 @@
+structure(list(method = "PUT", url = "https://api/workgroups/test_workgroup/twostepmandatory",
+    status_code = 204L, headers = structure(list(Date = "Mon, 22 Dec 2025 15:43:40 GMT",
+        `Content-Length` = "0", Connection = "keep-alive", `X-CONNECT-MDC` = "api8ac74669e4e222120b3a73403ee82c2c",
+        `X-Frame-Options` = "deny", `X-XSS-Protection` = "1; mode=block",
+        `Cache-Control` = "no-cache, no-store", Expires = "0",
+        Pragma = "no-cache", `Strict-Transport-Security` = "max-age=31536000 ; includeSubDomains",
+        `Content-Security-Policy` = "script-src 'self' 'unsafe-inline'",
+        `X-Content-Type-Options` = "nosniff", `Referrer-Policy` = "strict-origin-when-cross-origin",
+        `Feature-Policy` = "vibrate 'none'; geolocation 'none'",
+        Authorization = "REDACTED", `Set-Cookie` = "REDACTED"), class = "httr2_headers"),
+    body = raw(0), cache = new.env(parent = emptyenv())), class = "httr2_response")

tests/testthat/api/workgroups/test_workgroup/twostepmandatory-cf6ee1-PUT.R

@@ -34,6 +34,21 @@ without_internet({
       "{\"bypassTwoStep\":\"false\"}"
     )
 
+    expect_PUT(
+      workgroup_mandate_2fa(workgroup_uuid = "test_workgroup"),
+      paste0("https://secure.objectiveconnect.co.uk/publicapi/1/workgroups/",
+             "test_workgroup/twostepmandatory"),
+      "{\"twoStepMandatory\":\"true\"}"
+    )
+
+    expect_PUT(
+      workgroup_mandate_2fa(workgroup_uuid = "test_workgroup",
+                            mandate = FALSE),
+      paste0("https://secure.objectiveconnect.co.uk/publicapi/1/workgroups/",
+             "test_workgroup/twostepmandatory"),
+      "{\"twoStepMandatory\":\"false\"}"
+    )
+
   })
 
 })
@@ -54,12 +69,19 @@ with_mock_api({
       )
     )
 
+    expect_invisible(
+      suppressMessages(
+        workgroup_mandate_2fa("test_workgroup")
+      )
+    )
+
   })
 
   test_that("Functions return success message", {
 
     expect_message(workgroup_bypass_2fa("test_workgroup"))
     expect_message(participant_bypass_2fa("test_participant"))
+    expect_message(workgroup_mandate_2fa("test_workgroup"))
 
   })
 

tests/testthat/test-bypass_2fa.R

@@ -46,18 +46,36 @@ These steps must be completed by a **workgroup admin**.
 
 > If you work in the Scottish Government, please [contact the package maintainers](https://scotgovanalysis.github.io/objr/authors.html#authors) to arrange this step.
 
-1. <a name = "workgroup-1">Navigate to the summary page for your workgroup in Objective Connect. Select 'Workgroup Options', un-check the option to 'Enforce Two-step verification', and click the blue 'Update' button.</a>
+1. <a name = "workgroup-1">Temporarily disable mandatory 2FA in your workgroup.</a> This can be done in one of the following ways:
+
+   * Navigate to the summary page for your workgroup in Objective Connect. Select 'Workgroup Options', un-check the option to 'Enforce Two-step verification', and click the blue 'Update' button.
+
+   ```{r}
+   #| eval: true
+   #| echo: false
+   #| out.width: "50%"
+   #| fig-align: "center"
+   #| fig-alt: >
+   #|    A button for 'Workgroup options' is selected. A menu is visible    containing
+   #|    an option to 'Enforce Two-step verification' with a checkbox.
+   knitr::include_graphics("workgroup-2fa.png", dpi = "retina")
+   ```
 
-```{r}
-#| eval: true
-#| echo: false
-#| out.width: "50%"
-#| fig-align: "center"
-#| fig-alt: >
-#|    A button for 'Workgroup options' is selected. A menu is visible containing
-#|    an option to 'Enforce Two-step verification' with a checkbox.
-knitr::include_graphics("workgroup-2fa.png", dpi = "retina")
-```
+   * In R, use `workgroup_mandate_2fa()`, providing the relevant workgroup UUID and setting `mandate = FALSE` to disable. For example:
+
+      ```{r workgroup_mandate}
+      workgroup_mandate_2fa("v09y-g5vk-5348-k68t-s462-c2vs-7kl8-7440", mandate = FALSE)
+      ```
+
+      ```{r workgroup_mandate-output, eval = TRUE, echo = FALSE, message = TRUE}
+      cli::cli_alert_success(
+        "Mandatory 2FA setting successfully updated for workgroup."
+      )
+      ```
+      
+      To reinstate mandatory 2FA later, set `mandate = TRUE`.
+
+      > Non R users can also use the interactive documentation to [disable mandatory 2FA in the workgroup](https://secure.objectiveconnect.co.uk/publicapi/1/swagger-ui/index.html#/Workgroups/setTwoStepMandatory).
 
 
 2. In R, allow 2FA bypassing for the workgroup using `workgroup_bypass_2fa()`, providing the relevant workgroup UUID. For example:
@@ -74,7 +92,7 @@ knitr::include_graphics("workgroup-2fa.png", dpi = "retina")
 
    > Non R users can use the interactive documentation to [allow 2FA bypassing in the workgroup](https://secure.objectiveconnect.co.uk/publicapi/1/swagger-ui/index.html#/Workgroups/setWorkgroupMfaBypassAllowed).
 
-3. Continue to the next section to [give the workspace owner permission to bypass 2FA](#workspace-owner). Once this is complete, [reinstate 2FA enforcing for the workgroup](#workgroup-1).
+3. Continue to the next section to [give the workspace owner permission to bypass 2FA](#workspace-owner). Once this is complete, [reinstate mandatory 2FA for the workgroup](#workgroup-1).
 
 
 ## Permission for the workspace owner {#workspace-owner}
@@ -114,7 +132,7 @@ knitr::include_graphics("workspace-2fa.png", dpi = "retina")
 
 4. Reinstate 2FA for the workspace using the [same method as in step 1](#workspace-1).
 
-5. The workgroup admin can now [reinstate 2FA enforcing for the workgroup](#workgroup-1).
+5. The workgroup admin can now [reinstate mandatory 2FA for the workgroup](#workgroup-1).
 
 
 ## Permssion for other participants {#participants}