4.2 Configuring RStudio Connect
In this session#
In this session you:
- Make more choices about Connect configuration
- Edit the configuration file for essential setup
- Activate a license using the RStudio Floating License manager
In this chapter you will learn how to make choices to configure RStudio Connect.
; RStudio Connect configuration file [Server] ; SenderEmail = email@example.com SenderEmail = ; Address is a public URL for this RStudio Connect server. Must be configured ; to enable features like including links to your content in emails. If ; Connect is deployed behind an HTTP proxy, this should be the URL for Connect ; in terms of that proxy. ; ; Address = https://rstudio-connect.company.com Address = [HTTP] ; RStudio Connect will listen on this network address for HTTP connections. Listen = :3939 [Authentication] ; Specifies the type of user authentication. Provider = LDAP
The configuration file is at:
It has the Go Configuration File (
[Section Heading] Field = Value
For initial setup, you must set two fields in the
- Server address
- Sender email
[Server] Address = ... SenderEmail = ...
This field is the address your end users will enter to get to your RSC instance.
This implies a lot of choices:
- http(s) > Browser Security
- Load Balancing... Later
For now, you need the name of the training server (that you got earlier in the course).
This is the "From" address, i.e. the email address that Connect uses to send email.
This field does not complete email setup!
You must also configure a mail server, using either:
Your organisation will already have a an email gateway, and you should use this on your Connect instances.
Later in this course, during the exercises, you will use SMTP to send email.
(For your sanity during the course. Do not do this in production unless you have a good reason to do so!)
More configuration options#
Connect admin guide Appendix A: Configuration Options
One way to teach this class would be to go through each of the configuration settings.
- We are not going to do that.
- We are going to focus on using RStudio Connect and hit the options as we go.
We will not cover ALL of the options.
- Read through the rest of the config settings.
- Like the dentist: boring, important, and you should do it once a year.
Starting and Stopping#
Depends on operating system. See Stopping and Starting for complete instructions.
For the classroom VM using Ubuntu:
sudo systemctl stop rstudio-connect sudo systemctl start rstudio-connect
- Use for restart, but note that this causes downtime.
- In a production setting, if you already have running processes on your Connect server, you can use
reloadinstead, since this picks up some configuration changes:
sudo systemctl reload rstudio-connect
- only system settings flagged with
Reloadable: truewill be affected if you use
- See the admin guide appendix.
A few types of logs:
- Server log
- Access log
- Application logs (deployed content)
ls /var/log/rstudio-connect.* sudo tail /var/log/rstudio-connect.log
Run the commands and view the log output
RStudio Connect supports both online and offline license activation:
- Online: servers can activate automatically
- Offline: licenses require manual exchange.
Online servers automatically start with a 45 day trial.
License can be activated with:
sudo /opt/rstudio-connect/bin/license-manager activate KEY
Offline servers require a 3 step activation for both trials and full licenses.
- Step 1: Run a command to generate an XML file.
- Step 2: Use the XML file to generate a key.
- Step 3: Activate the license with the key.
In special circumstances, there is an alternative licensing mechanism called floating licenses.
Some use cases for floating licensing:
- You have multiple server installations to manage
- Some of these are transient / fleeting
- You have transient servers, e.g. staging server
- You manage a rotating blue/green production server setup
Chapter 3.7 of the Connect admin guide discusses Floating Licenses in more detail.
It's Alive! Can I use it?#
Not yet. More choices to make:
- Initial Configuration
- Auth Provider
User Management and Authentication#
This breaks down into three parts:
|1.||Authentication||Who can access RStudio Connect?|
|2.||User Role||What can a user do on RStudio Connect?|
|3.||ACL||What can a user do to a piece of content on RStudio Connect|
Part 1: Authentication#
Who can access RStudio Connect? (Authentication)
Irrevocable choice, but an easy choice.
To answer who can access RStudio Connect, you must first tell Connect where users are defined.
|My user information lives||Then|
|Nowhere. I thought Connect would handle users?||Use password auth and manage users in Connect.|
|Active Directory||Configure Connect to get user information via LDAP.|
|Active Directory AND I need to pass user credentials through Connect to a backend||Connect will rely on local Unix accounts via PAM. Each user will need a local account.|
|Configure Connect to get user information from Google OAuth2.|
|Azure AD, Okta, OneLogin, other SAML||Configure Connect with SAML|
|Somewhere else||Going to need proxied auth.|
In this class you will integrate RStudio Connect with the LDAP server on the leader instance for this classroom.
This is similar to what you will do most likely do in your organization, if LDAP or Active Directory is used. However, the details in your organization will be different. Be sure to get in contact with the respective IT team and refer to the LDAP section in the admin guide.
Hint, use the following setting to get more descriptive messages in your log file.
[Debug] Log = ldap
Now that you're logged in, what about other users?
- For password auth an admin can register a user. But where does the password come from? Email setup.
- For LDAP:
- Users must self-register (but you can limit who can self register via the
- Users must self-register (but you can limit who can self register via the
Using the email print provider
A secret trick
- Connect sends email for lots of things, and it is important to configure.
- In some exceptional circumstances you may want to use a secret trick:
Do not use this for this class
[Server] EmailProvider = print
This prints all email to the log file, bypassing
sudo tail /var/log/rstudio-connect.log
Some of our partners use this for automated configuration testing.
Other Users - LDAP?#
For LDAP authentication:
- Users must still self-register
- but you can limit who can self register by using:
Other Users - Other Providers?#
|Attribute||Built-in Password auth||LDAP||Google OAuth2||PAM||SAML||Proxy|
Authentication - Other Methods#
- Configuration is limited in Connect, extensive in PAM.
- Copy the
sshlogin PAM profile as a basis for a custom profile.
- Set up a proxy (e.g. using
Apache) in front of Connect to handle all user auth.
- The proxy passes a secure header to tell Connect who the user is.
- This will generally require a proxy plug-in to implement the authentication within the proxy layer.
Authentication - Groups#
Connect supports groups, but only for some authentication schemas:
- LDAP groups will automatically be identified and can be used for access control.
- For Password auth, groups can be created and managed by admins.
- But note that proxied auth does not support groups.
- What can a user do on RStudio Connect? (User Role)
- What can a user do to a piece of content on RStudio Connect? (ACL)
Connect allows 4 different types of user roles:
Configuration of user roles#
- Option 1: Admin can set default user roles
- Specifies what abilities given to a newly created user. Allowed values are publisher or viewer
- Option 2: Connect UI
- Admin can change user role in the Connect UI
- Option 3: Command line interface (CLI)
Other advanced topics#
Security Best Practices#
Connect admin guide:
- SSL and friends (secure cookies enabled, CORS, click-jacking)
- Session timeouts
This is covered in the Browser security section of the Connect admin guide.
What about data governance? Later in the course you will become familiar with sandboxing in Connect.
Same process as the initial installation.
- Download the new binary.
- Install the new binary on top of the existing installation.
- Will restart the service.
Load balancing / High availability#
Only 3 changes to your setup.
- Shared Storage
- Postgres DB
- Sticky load balancer
Connect Admin Guide: High Availability and Load Balancing
In this chapter you learned about some of the decision points when configuring a Connect instance.
The exercises will guide you through these steps for one specific branch:
- LDAP auth
- floating license manager
- single instance
In subsequent chapters you will start using RStudio Connect and deploying content to your machine.
Now complete the lab exercise.
Signs of success:
- You have a running instance of RStudio Connect
- You have working email integration
- You have multiple users, and you can log in using their LDAP credentials