unlockREDCap: Open REDCap connections using cryptolocker for storage of...
In nutterb/redcapAPI: Interface to 'REDCap'

unlockREDCap

R Documentation

Open REDCap connections using cryptolocker for storage of API_KEYs.

Description

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.

Usage

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()`.

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

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").

Value

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

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)

nutterb/redcapAPI documentation built on Feb. 11, 2024, 11:20 p.m.