The user authentication in Shiny applications can be very useful. Mainly, user can login to read and write some results of their session into relational database.
On the other hand, it may be handy for your App to allow access of unregistered users. If you need to secure your ShinyApp, there are better alternatives (shinymanager or shinyauthr)
This package contains modules to use in your Shiny application allowing you to automatically insert boxes for login, register, credentials edit and password reset and procedures.
shiny.reglog supports as data containers either databases
accessed with RSQLite
, RMariaDB
,
RMySQL
and RPostgreSQL
drivers or
googlesheets-based database (accessed by googlesheets4
package).
It is highly recommended to use one of the DBI
-supported
databases, though. It is much more optimized and secure, as the database
is never loaded as a whole into the memory, but queried as needed.
googlesheets database is much easier to set-up, but it
shouldn’t be used when you are expecting big userbase.
Registration, credentials edit and password reset procedures
programmatically send email to the user of your ShinyApp - to welcome
them, inform about change of their user ID and/or email and to give them
a reset code to reset their password. shiny.reglog supports two
methods of email sending: via emayili
or
gmailr
packages. Both of them have their pros and cons,
depending on your accesses: emayili
allows for usage of
many SMTP servers, while gmailr
allowing using
gmail messaging via Google REST API.
The emayili
is recommended for most applications.
gmailr
can be useful if you already have application
registered and authorized with mail sending scope.
Currently the package is after major change in its code - basically full rewrite to allow more security, usage of more databases and more customization. Past functions are still available in current version, but will generate deprecation warnings.
Basic information about shiny.reglog is contained within this document. There are some more resources to learn about its usage:
RegLogDemo()
function. It will use mocked
mailConnector by default or RegLogEmayiliConnector if
you provide it arguments required by emayili
backend.There are three main objects that are to be used when implementing RegLog system for login and registration in your ShinyApp. All of them need to be defined in the server code.
RegLogDBIConnector
or
RegLogGsheetConnector
. It will handle all writes, edits and
inputs to the users database.RegLogEmayiliConnector
or RegLogGmailrConnector
. It will handle all automatical
emailing to the user emails.You can install this version of shiny.reglog from GitHub with:
# install last stable release from CRAN
install.packages("shiny.reglog")
## or development version from GitHub
install.packages("devtools")
::install.github("StatisMike/shiny.reglog") devtools
You need to create dbConnector object to be used by the RegLogServer to write and read user data from the database.
To set-up the database for RegLog system, you can use helper functions included in this package. They are tested and guarantee compatible structure of the data.
gsheet_tables_create()
function, which by default
creates empty spreadsheets configured correctly.# create googlesheet and gather its id for later usage
# you can also specify optional 'name' argument for custom gsheet name
<- gsheet_tables_create()
gsheet_id
# save you gsheet_id - you need to provide it later to your dbConnector
If you wish to import some existing credentials, you can do it by
giving the data.frame
object to the user_data
argument:
# get some credentials
<- data.frame(
credentials username = "ShinyReglogTest",
password = "VeryHardPassword",
email = "shinyreglog@test"
)
# create gsheet database with some credentials
<- gsheet_tables_create(
gsheet_id user_data = credentials,
# as the password was not hashed with `script` before,
# it need to be hashed now
hash_passwords = T)
Configure googlesheets4 package to use out-of-band (non-interactive) auth. For more information about it visit googlesheets4 documentation.
In the server
part of your ShinyApp define
RegLogGsheetConnector
to provide it afterwards to the
RegLogServer
object
<- function(input, output, session) {
server
<- RegLogGsheetConnector$new(
dbConnector gsheet_ss = gsheet_id)
}
DBI
compatible SQL database
(RegLogDBIConnector)RegLog system out of the box supports SQLite,
MySQL, MariaDB and PostgreSQL databases. You
can use DBI_tables_create
function, which by default
creates empty tables configured correctly.
# create a connection to the database. Remember to use user with CREATE TABLE
# scope enabled when useing MySQL, MariaDB or PostgreSQL connection
<- DBI::dbConnect(
conn ::SQLite(),
RSQLitedbname = "reglog_db.sqlite"
)
# using this connection create the tables.
DBI_tables_create(conn = conn)
# disconnect from the database after creation
::dbDisconnect(conn) DBI
If you wish to import some credentials, you can do it by providing
the data.frame
object to the user_data
argument:
# get some credentials
<- data.frame(
credentials username = "ShinyReglogTest",
password = "VeryHardPassword",
email = "shinyreglog@test")
<- DBI::dbConnect(
conn ::SQLite(),
RSQLitedbname = "reglog_db.sqlite"
)
# create database using the connection
DBI_tables_create(
conn = conn,
user_data = credentials,
# as the password was not hashed with `script` before,
# it need to be hashed now
hash_passwords = T)
::dbDisconnect(conn) DBI
RegLogDBIConnector
to provide it afterwards to the
RegLogServer
object.<- function(input, output, session) {
server
<- RegLogDBIConnector$new(
dbConnector driver = RSQLite::SQLite(),
dbname = "reglog_db.sqlite")
}
MongoDB
-based connector
(RegLogMongoConnector)MongoDB is very popular NoSQL database with pretty low entry-point. Connector is still experimental.
Setup is analogous to other database connectors. For more
informations, refer to documentation:
?mongo_tables_create()
,
?RegLogMongoConnector
You need to create mailConnector object to be used by the
RegLogServer to write and read user data from the database.
There are two classes defined to use emayili
or
gmailr
packages as backend.
emayili
(RegLogEmayiliConnector)This backend is recommended to use. It supports many SMTP servers, mostly with username and password based identification.
<- function(input, output, session) {
server
<- RegLogEmayiliConnector$new(
mailConnector from = "email@sending.com",
# to learn how to setup emayili smtp server read ?emayili::server
smtp = emayili::server(...)
)
}
gmailr
(RegLogGmailrConnector)This backend is only viable if you have an app registered in Google Cloud Console. It authorizes and sends email via gmail REST API, needing Oauth authorization with high scopes.
<- function(input, output, session) {
server
<- RegLogGmailrConnector$new(
mailConnector from = "email@gmail.com"
)
}
All of RegLog system is generated and maintained by
the object of class RegLogSystem
in unison with
dbConnector and mailConnector of your choosing.
Its setup is pretty straightforward:
<- function(input, output, session) {
server
<- RegLogServer$new(
RegLog # both of these elements need to be defined firstly or in this call
dbConnector = dbConnector,
mailConnector = mailConnector
) }
Besides these two mandatory arguments, there are also some additional arguments to be used for customization.
app_name
: your application name. It will be used within
emails send to users. If not specified, the name of the folder
containing you application files will be used.app_address
: URL address to your application. It will
be used within emails send to users. If not specified, the email address
contained within session$clientData will be used.lang
: language to be used in UI elements and send
emails. Defaults to ‘en’ for English. Currently also ‘pl’ for
Polish is supported. Besides that, you can also specify ‘i18’
to generate only text indicators - external methods can be used to parse
the message in given language can be then used (eg.
shiny.i18n
package).custom_txts
: named list with character strings of
custom texts to be used by the system. For more information call
?RegLog_txt
.use_modals
: either boolean indicating if all default
modalDialogs should be shown or named list of FALSE
values
inhibiting specific ones. For more information read RegLogServer
object fields and methods, section Message.
All modals are listed there alongside conditions of their
appearance.module_id
: character string with ID of the module.
Recommended to leave as default - unless if that name is taken by
another module.After setting up and assigning the object your application logic can observe status of user in current session by public fields containing reactiveVal objects.
## if you assigned the RegLogServer to 'RegLog' object, as in examples above:
# boolean showing if the user is logged in:
$is_logged()
RegLog
# character vector containing user ID: either specific to the user if logged
# in, or unique anonymous ID generated with 'uuid::UUIDgenerate()'
$user_id()
RegLog
# character vector containing user email if logged in
$user_mail()
RegLog
# integer of the account ID inside the database - for identifying the logged user
# across relative tables
$account_id() RegLog
There are much more to be learned about RegLogServer object - for more information read RegLogServer object fields and methods. Above information is enough for basic setup.
Every part of the UI is generated by RegLogServer, and could
be accessed by provided functions containing tagList
.
Providing GUI to allow logging in if user is already registered to your application.
RegLog_login_UI()
Providing GUI for registering new account.
After account registration, user will receive confirmation email on their password.
RegLog_register_UI()
Providing GUI for changing credentials.
RegLog_credsEdit_UI()
Providing GUI for password reset.
RegLog_resetPass_UI()