Profile
Jack Scanlon
2024-09-09
Profile.Rmd
The saildb::Profile
class
This R6
class is intended to be used as a secret manager
for SAIL DB authentication; it’s primarily intended to be used
internally by saildb::Connection but it
has been exported for use as it might be useful for your other
projects.
If you’re only interested in using the SAIL database interface,
i.e. the saildb::Connection
class, then you can
safely ignore this documentation!
Getting Started
Note: This is a lightweight
R6
wrapper around theKeyring
package +/- changes to improve accessibility & ease of use within SAIL Databank. TheKeyring
package is available on Cran and both authored and maintained by Gabor Csardi. Github repository is available outside SAIL’s Gateway TRE here
Creating a saildb::Profile
instance
Note: Don’t forget to load the package into your enviroment by entering the following:
library(saildb)
You can create a Profile
instance by entering the
following:
profile = Profile$new(
# Sets the keychain name, i.e. the name of the keychain that contains
# the secrets defined by the profile
#
# NOTE:
# - Defaults to `SAILDB` but can be changed to any other name if you'd prefer
# to separate your secrets between applications
#
keychain.name = 'SAILDB'
)
Or, you could grab your Profile
instance from an active
saildb::Connection
like so:
db = Connection$new() # if you haven't already connected
# Get the active profile (if any)
profile = db$get.profile()
Example usage
Please see example usage below:
profile = Profile$new() # if you haven't already got a profile instance
# Attempt to check whether we have a secret for a username
# associated with a database
#
# NOTE: the database argument defaults to `PR_SAIL`
#
profile$has.secrets('some_username', 'some_database')
# Attempts to collect the secrets associated with the specified
# username and database
#
# NOTE: the database argument defaults to `PR_SAIL`
#
profile$get.secrets('some_username', 'some_database')
# Checks whether the 'super.secret.password' is the secret stored within
# the profile for the 'some_username' account for the 'some_database' database
#
# NOTE: the database argument defaults to `PR_SAIL`
#
profile$is.secret('some_username', 'super.secret.password', 'some_database')
# Sets or creates & stores the secret for the 'some_username' account
# with the 'super.secret.password' secret, associated with the 'some_database' database
#
# NOTE: the database argument defaults to `PR_SAIL`
#
profile$is.secret('some_username', 'super.secret.password', 'some_database')
# Attempts to remove the 'some_username' secret associated with the 'some_database' database
#
# NOTE: the database argument defaults to `PR_SAIL`
#
profile$get.secrets('some_username', 'some_database')
# Field members...
## Get the current keychain name associated with this profile
profile$keychain.name
## Get the username of the account associated with this machine
profile$system.user
# Static methods...
## Check if some object is a `saildb::Profile`
##
## NOTE:
## - Static methods CANNOT be accessed via the `profile` instance;
## they can only be accessed via the top-level class like below:
##
if (Profile$is(profile)) {
print('It is a Profile!')
}
try({
profile$is(profile) # this will fail!
})
## Attempt to clear a secret associated with a username and database
##
## NOTE:
## - As above, this can only be accessed by the top-level class
## - The latter argument defaults to `SAILDB` and describes the keychain name (optional; defaults to `SAILDB`)
##
Profile$clear('PR_SAIL:some_username', 'SAILDB')