Configuring Audit Permissions

Overview

{dsROCrate} audits a DataSHIELD server by reading information that ordinary analyst accounts cannot see. This vignette explains:

what is read and why elevated permissions are needed,
how {dsROCrate} checks that your account is suitable,
how to create a dedicated auditor account (Opal),
what to do when the check fails.

Supported backends

Backend	Status	Required account
OBiBa Opal	Supported (Opal 5.7.2 or later)	Administrator, or a user with the `Audit system` permission
MOLGENIS Armadillo	In development	–

Why are elevated permissions required?

An audit reads (and never changes) the following:

the DataSHIELD logs: who did what and when,
the DataSHIELD settings (e.g., disclosure controls) and the R packages installed on the server, for each profile,
the user accounts and groups,
the system-level permissions, used to tell administrators and auditors apart from regular users,
the projects and their tables and resources, with their permissions.

Standard user accounts cannot access most of this, so without suitable permissions {dsROCrate} cannot build the Safe People, Safe Setting and Safe Output parts of the RO-Crate.

How the permission check works

Every init(), safe_*() and audit() call first runs check_permissions(), which you can also call yourself:

con <- opalr::opal.login(
  username = "audit_user",
  password = "secret",
  url = "https://opal-demo.obiba.org"
)

dsROCrate::check_permissions(con, verbose = TRUE)
#> You are ready to audit this system!

For Opal, the check tries two harmless requests with your account:

looking up user accounts, which only administrators are allowed to do,
looking up the DataSHIELD profiles, which administrators and users with the Audit system permission are allowed to do.

The account is accepted when both succeed (an administrator) or when the second succeeds and the first is refused (an auditor). Anything else is rejected with the error:

The supplied backend connection does not have sufficient permissions.

{dsROCrate} requires elevated permissions to perform audit operations.
...

Other checks run at the same time: the connection must still be valid, and the server must be Opal 5.7.2 or later (the Audit system permission was introduced in Opal 5.7).

Opal: create an audit user

Note: menu labels may differ slightly between Opal versions.

Step 1: Log in as an administrator

Step 2: Create a user (optional)

If a dedicated audit user does not exist yet:

Open the Administration tab.
Under Data Access, select Users and Groups.
Create a new user account for auditing purposes.

We recommend a dedicated account, separate from the analysts’ accounts, so the audit user has no more access than it needs.

Step 3: Grant audit permissions

Return to the Administration tab.
Under System, select General Settings.
Open the Permissions section.
Click the + button.
Select Add user permission.
Enter the username of the audit user.
Select Audit system.
Click Submit.

Step 4: Check the account

Log in as the audit user and run check_permissions(), as shown in the previous section. You can now use this connection with audit(), see vignette("getting-started", package = "dsROCrate").

Troubleshooting

Message	Likely cause and fix
`The supplied backend connection does not have sufficient permissions.`	The account is neither an administrator nor an auditor. Check that the user was granted Audit system (step 3) and, if you were already logged in when the permission was granted, log in again.
`Opal >= 5.7.2 is required, but server version is X.Y.Z.`	The server is too old. Upgrade Opal.
`The given connection is not valid!`	The connection object is no longer usable (e.g., it was saved and reloaded, or the session was closed). Create it again with `opalr::opal.login()`.
The `project = 'NAME'` was not found in the given Opal connection!	The project name is misspelled, or it does not exist on this server.

If the message is not listed here, please open an issue.