unlockREDCap function

Open REDCap connections using cryptolocker for storage of API_KEYs.

Opens a set of connections to REDcap from API_KEYs stored in an encrypted keyring. If the keyring does not exist, it will ask for password to this keyring to use on later requests. Next it will ask for the API_KEYs specified in connections. If an API_KEY does not work, it will request again. On later executions it will use an open keyring to retrieve all API_KEYs or for a password if the keyring is currently locked.

unlockREDCap(
  connections,
  url,
  keyring,
  envir = NULL,
  passwordFUN = .default_pass(),
  ...
)

Arguments

• connections: character vector. A list of strings that define the connections with associated API_KEYs to load into environment. Each name should correspond to a REDCap project for traceability, but it can be named anything one desires. The name in the returned list is this name.
• url: character. The url of one's institutional REDCap server api.
• keyring: character. Potential keyring, not used by default.
• envir: environment. The target environment for the connections. Defaults to NULL which returns the keys as a list. Use globalenv() to assign in the global environment. Will accept a number such a '1' for global as well.
• passwordFUN: function. Function to get the password for the keyring. Usually defaults getPass::getPass. On MacOS it will use rstudioapi::askForPassword if available.
• ...: Additional arguments passed to redcapConnection().

Returns

If envir is NULL returns a list of opened connections. Otherwise connections are assigned into the specified envir.

Details

If one forgets the password to this keyring, or wishes to start over: keyring::keyring_delete("<NAME_OF_KEY_RING_HERE>")

Consistent behavior requires options(keyring_backend=keyring::backend_file) to be set. It is recommended to place this in ~/.Rprofile.

For production servers where the password must be stored in a readable plain text file, it will search for ../<basename>.yml. DO NOT USE this unless one is a sysadmin, as this defeats the security and purpose of a local encrypted file. The expected structure of this yaml file is as follows:

other-config-stuff1: blah blah
redcapAPI:
  keys:
    intake: THIS_IS_THE_INTAKE_DATABASE_APIKEY
    details: THIS_IS_THE_DETAILS_DATABASE_APIKEY
other-config-stuff2: blah blah
other-config-stuff3: blah blah

For production servers the use of ENV variables is also supported. The connection string is converted to upper case for the search of ENV. If a YAML and ENV variable both exist, the YAML will take precedence.

IMPORTANT: Make sure that R is set to NEVER save workspace to .RData as this is writing the API_KEY to a local file in clear text because connection objects contain the unlocked key in memory. Tips are provided in vignette("redcapAPI-best-practices").

Examples

## Not run:

options(keyring_backend=keyring::backend_file) # Put in .Rprofile

unlockREDCap(c(test_conn    = 'TestRedcapAPI',
               sandbox_conn = 'SandboxAPI'),
             keyring      = '<NAME_OF_KEY_RING_HERE>',
             envir        = globalenv(),
             url          = 'https://<INSTITUTIONS_REDCAP_DOMAIN>/api/') 
## End(Not run)

See Also

redcapConnection()

Vignettes

vignette("redcapAPI-best-practices"),

vignette("redcapAPI-getting-started-connecting")