RStudio Connect supports a variety of user authentication options. Without customization, a locally-backed password scheme is used. You can learn more about password authentication in Section 10.3.
When signing into RStudio Connect, a session cookie is used to keep a user logged in for 30 days. The lifetime of these sessions can be altered using the Authentication.Lifetime setting.
External authentication is available through the following integrations:
- LDAP and Active Directory (Section 10.4)
- OAuth 2.0 using Google Apps accounts (Section 10.5)
- PAM (Section 10.6)
- Proxied Authentication (Section 10.7)
Authentication.Provider property with an authentication scheme appropriate for your organization. See Section A.6 for details
Here is a partial configuration which chooses to use LDAP.
[Authentication] Provider = ldap
10.1 Changing Authentication Provider
Migrating from one authentication provider to another (for example, switching from password to LDAP) is NOT SUPPORTED. If changing the style of authentication is absolutely necessary, you will need to completely purge and reinstall RStudio Connect. See Section 5.5 for instructions.
10.2 Username requirements
When using OAuth or Password authentication, users are required to choose a valid username when first logging in. Usernames must:
- be 3-64 characters in length,
- start with a letter, and
- contain only alphanumeric characters, underscores, and periods.
The LDAP, PAM, and Proxy authentication providers require by default that a valid username is received from the provider. If a valid username is not received from the provider, an error will be thrown. If you wish for less restrictive behavior where the user is prompted for a valid username, please use the
RequireExternalUsernames = false configuration setting for your auth provider. When using LDAP, the
LDAP.UsernameAttribute configuration setting specifies how Connect can find the username. When using PAM and Proxy authentication, Connect receives the exact username specified during login.
The LDAP, PAM, and Proxy authentication providers use relaxed username requirements. These providers accept any username, excepting a list of blacklisted usernames. The list of blacklisted usernames follows:
Password authentication is the default authentication provider used by RStudio Connect. This is a local user account backed by the RStudio Connect database and is not integrated with a third-party service.
Users will be able to create accounts when they first visit the system and will provide profile details at that time. An administrator will also be able to create new accounts.
Password authentication may be appropriate in small organizations without centralized IT systems.
RStudio Connect will use password authentication if the
Authentication.Provider setting has a value of
password or if
Provider is not present in the configuration file.
[Authentication] Provider = password
10.4 LDAP and Active Directory
RStudio Connect can integrate with your company’s LDAP or Active Directory (AD) infrastructure. User authentication and user search requests will be directed to the LDAP/AD server.
LDAP and Active Directory support in RStudio Connect has the following constraints:
- Your LDAP/AD user objects must contain a user’s first name, last name, email address, and username.
- Changes to a user (e.g. their name, email address, or username) will not propagate to RStudio Connect once the user is created internally.
- When using single bind, the DN of a user must contain their username (i.e. must utilize the
UsernameAttribute). For example, it is not supported if the DN for a user is
cn=SueJacobs,ou=People,dc=company,dc=combut their actual username is stored in the
SAMAccountNameLDAP attribute. You must use double bind when the DN does not contain the username.
- When using a single bind configuration, searches will only include users who have previously logged into RStudio Connect.
- When using a single bind configuration, groups will be unavailable.
- A username or DN containing a forward slash (
/) is not supported.
When attempting to troubleshoot a problem relating to LDAP, you can enable more verbose logging by adding
Debug.Log section in the configuration.
[Debug] Log = ldap
10.4.1 Defining an LDAP or AD section
RStudio Connect does support the notion of having multiple LDAP or AD servers. This can be utilized by defining multiple LDAP sections.
To define an LDAP or AD section in the configuration file, add a header like the following:
[LDAP "European LDAP Server"] ...
An LDAP/AD configuration section header is always bounded by square brackets (
). After the section type LDAP is the effective name of the LDAP or AD server (
"European LDAP Server" in the example). Make sure that this text is unique per LDAP or AD section you configure. The LDAP section name is treated case sensitively.
RStudio Connect can support more than one LDAP server through multiple, uniquely named LDAP configuration sections. Other complex LDAP configurations can also be achieved by using multiple LDAP sections.
If multiple LDAP sections have the same name, they will be combined as described in Appendix A. As this is unlikely your intent, please take care to give unique names to each LDAP configuration section.
Here is an sample configuration using two LDAP sections.
[LDAP "European LDAP Server"] ... [LDAP "Statistics Department LDAP Server"] ...
Each of these sections will have a variety of configuration settings, which are explained below.
10.4.2 Complete Configuration Example
Here is a complete LDAP configuration as an example. Here, we are communicating with an OpenLDAP server on the local host; see the documentation for
ServerAddress to learn how to direct requests elsewhere. The other settings will probably need adjustment for your environment. Talk to your LDAP administrator if you need help with your organization’s LDAP hierarchy.
[LDAP "Sample OpenLDAP Configuration"] ServerAddress = 127.0.0.1:389 BindDN = "cn=admin,dc=example-openldap" BindPassword = "XXXXXXXX" UserSearchBaseDN = "ou=People,dc=example-openldap" UsernameAttribute = "uid" UserObjectClass = "posixAccount" UserEmailAttribute = mail UserFirstNameAttribute = givenName UserLastNameAttribute = sn
This sample configuration assumed a very simple OpenLDAP structure; here is a sample user record to show the mapping between LDAP records and RStudio Connect LDAP configuration.
dn: uid=john,ou=People,dc=example-openldap objectClass: inetOrgPerson objectClass: posixAccount objectClass: shadowAccount uid: john sn: Doe givenName: John cn: John Doe displayName: John Doe uidNumber: 10000 gidNumber: 5000 userPassword: johnldap gecos: John Doe loginShell: /bin/bash homeDirectory: /home/john mail: firstname.lastname@example.org
More LDAP configuration scenarios can be found in Appendix D.
10.4.3 LDAP or AD Configuration Settings
ServerAddress (required) is used to define the location of the LDAP/AD server. This should contain an IP address or DNS address, and a port (colon separated). Most LDAP/AD servers operate on port
636 (for SSL). But you can specify any port that fits your environment.
ServerAddress = 127.0.0.1:389 ServerAddress = ldap.company.com:389 ServerAddress = ldaps.company.com:636 ServerAddress = private.internal.local:7554
TLS is a Boolean (true/false) attribute that causes all connections to your LDAP/AD server to use TLS (SSL). The default value for this is
false. This cannot be enabled if
TLS = true TLS = false
StartTLS is a Boolean (true/false) attribute that causes connections to your LDAP/AD server to initially use an unencrypted channel but then upgrade to a TLS connection using “Opportunistic TLS”. The default value for this is
false. This cannot be enabled if
StartTLS = true StartTLS = false
At present, the error messages associated with StartTLS problems can be cryptic. If you’re encountering issues while configuring StartTLS, consider adding debug logging for LDAP by including the following line in your configuration file.
[Debug] Log = ldap
TLSCACertificate is a file location that is a certificate authority that is used to connect to an LDAP server securely. This file should be in PEM format.
ServerTLSInsecure is a Boolean (true/false) attribute that allows insecure TLS connections. This controls whether a client will verify the server’s certficate chain and host name. If this is
true, RStudio Connect will accept any certificate presented by the server and any host name in that certificate. Setting to
true is susceptible to main-in-the-middle attacks, but is required if, for example, your server uses a self-signed certificate. The default value is
ServerTLSInsecure = true ServerTLSInsecure = false
BindPassword are credentials used to connect to an LDAP/AD server to authenticate, search for users, and other functionality. While it is encouraged to specify these two attributes (a.k.a. “double bind”), it is not required (a.k.a. “single bind”). These credentials should have read-only administrator’s rights, if configured.
If you do not specify these attributes, some functionality of RStudio Connect will not work. For example, searching for users to add as collaborators, or sending email documents will only work partially.
# Example DN BindDN = uid=john,ou=People,dc=company,dc=com BindPassword = johnpassword # Example UPN BindDN = email@example.com BindPassword = adminpassword # Example NT-style login BindDN = COMPANY\\admin # we use double slashes (\\) to character escape the last slash BindPassword = adminpassword
AnonymousBind instructs RStudio Connect to establish an anonymous bind to your LDAP/AD server. For organizations that support anonymous binds, you may use this option instead of
For this to work properly, your LDAP server must allow anonymous binds to search and view all pertinent groups, group memberships, and users.
AnonymousBind = true
UserSearchBaseDN (required) is the starting point from which RStudio Connect will search for user entries in your LDAP/AD server.
UserSearchBaseDN = dc=company,dc=com UserSearchBaseDN = ou=People,dc=company,dc=com
UserObjectClass (required) is the
objectClass that a user in your LDAP/AD structure will have. Common examples of this are
UserObjectClass = user UserObjectClass = posixAccount
UsernameAttribute (required, case-sensitive) is the LDAP entry attribute that contains the username of a user.
UsernameAttribute = uid UsernameAttribute = sAMAccountName
UserFirstNameAttribute (required, case-sensitive) is the LDAP entry attribute that contains the first name of a user.
UserFirstNameAttribute = givenName
UserLastNameAttribute (required, case-sensitive) is the LDAP entry attribute that contains the last name of a user.
UserLastNameAttribute = sn
UserEmailAttribute (required, case-sensitive) is the LDAP entry attribute that contains the email address of a user.
UserEmailAttribute = mail
WhitelistedLoginGroup defines a group DN that a user must be a member of in order to login into Connect. You can specify this attribute multiple times. Be aware that this feature restricts only the ability for users to login. Users not in this group could still be referenced when setting access controls for content or as email recipients. Because the users could not login, they would not be able to access content even if they were added as a viewer or collaborator, but they might still be able to receive emailed versions of reports.
WhitelistedLoginGroup = cn=admins,ou=group,dc=company,dc=com WhitelistedLoginGroup = cn=scientists,ou=group,dc=company,dc=com
GroupUserObjectClass is the
objectClass that a group in your LDAP/AD structure will have. Common examples of this are
GroupObjectClass = group GroupObjectClass = posixGroup
GroupNameAttribute (case-sensitive) is the LDAP entry attribute that contains the name of a group.
GroupNameAttribute = cn GroupNameAttribute = sAMAccountName
GroupSearchBaseDN is the starting point from which RStudio Connect will search for group entries in your LDAP/AD server.
GroupSearchBaseDN = dc=company,dc=com GroupSearchBaseDN = ou=Groups,dc=company,dc=com
10.5 OAuth2 (Google)
OAuth2 authentication is available to authenticate against the Google OAuth2 service.
RStudio Connect will use OAuth2 authentication if the
Authentication.Provider setting has a value of
[Authentication] Provider = oauth2
Appendix A.8 contains information about each OAuth2 configuration option.
In order for RStudio Connect to use Google as an OAuth2 service, you will need a client ID and client secret.
10.5.1 Obtaining a Client ID and Client Secret
These instructions tell you how to obtain an OAuth2 client ID and client secret. We recommend a distinct set of credentials for each application you configure to use the Google OAuth2 service.
- Visit the Google Developers Console and create a new project. Give it a name of your choosing, such as “rstudio-connect”.
- Once the project is created, locate and enable the “Google+ API”.
- In the left navigation window, click on “Credentials”, then goto the “OAuth consent screen” tab, fill in the information requested and click “Save”.
- Once again, click “Credentials” in the left navigation window. Then click the dropdown button “New credentials”, then “OAuth client ID”.
https://HOST:PORT). For “Authorized redirect URIs”, use your RStudio Connect server address with
- Click “Create”. Your client ID and client secret will be shown to you.
Add the client ID and secret to your configuration file as shown in the example below.
[OAuth2] DiscoveryEndpoint = https://accounts.google.com/.well-known/openid-configuration ClientId = <CLIENT ID> ClientSecret = <CLIENT SECRET>
ClientId and either
ClientSecretFile configured, you can use your Google Apps account to sign into RStudio Connect!
10.5.2 Restricting Access
The default configuration allows all Google account holders to access RStudio Connect. We recommend that you limit access to specific domains that are used by your organization.
Verify that you can use your Google Apps account to sign into RStudio Connect before attempting to configure access restrictions.
OAuth2.AllowedDomains setting specifies the set of domains that are allowed to access your RStudio Connect server. Multiple domains should be space-separated.
[OAuth2] AllowedDomains = company.com subsidiary.com
You may also restrict access by email address if using domain alone is insufficient. The
OAuth2.AllowedEmails setting specifies the set of email addresses that are allowed to access your RStudio Connect server. Multiple addresses should be space-separated.
[OAuth2] AllowedEmails = firstname.lastname@example.org email@example.com
It is important to understand how the
AllowedEmails properties interact.
AllowedDomains is configured, only email addresses with a listed domain will be permitted access.
AllowedEmails is configured, only listed email addresses will be permitted access.
AllowedEmails are specified, email addresses given in
AllowedEmails are permitted access in addition to email addresses with a domain listed in
RStudio Connect allows users to search for collaborators against the user directory associated with your Google Apps account. That search is performed on behalf of the current user. Different accounts may have different visibility within the user directory and therefore will see different results. This is most obvious when you have configured RStudio Connect to allow access to two different domains. Users in
company.com, for example, will likely not be able to search for colleagues in
RStudio Connect augments the Google Apps user directory search with a local search across its set of known accounts. Once your colleague has created their own RStudio Connect account, they will become discoverable.
RStudio Connect can use PAM for user authentication. PAM authentication is used if the
Authentication.Provider setting has a value of
[Authentication] Provider = pam
See Section 12.5 for information about using PAM sessions when launching R processes.
You can change the PAM service name used for authentication by customizing the
PAM.Service setting. The default PAM service name used for authentication is
[PAM] Service = rstudio-connect
We assume that RStudio Connect is configured to use the
rstudio-connect PAM service name in the examples that follow.
RStudio Connect does not create a PAM service on Ubuntu systems. When RStudio Connect attempts to use the
rstudio-connect service name for authentication, PAM will recognize that there is no service with that name and fall back to the default
other service located at
The default Ubuntu
other service is configured to inherit from a set of common PAM services:
# Ubuntu default "other" PAM service. @include common-auth @include common-account @include common-password @include common-session
other service is appropriate for your organization, no further configuration is needed.
You need a custom
rstudio-connect PAM service for RStudio Connect only if the
other service is not fitting for your users. Create and configure
/etc/pam.d/rstudio-connect to prevent PAM from falling back to the
other service. PAM will use this service for subsequent authentication attempts using the
rstudio-connect service name.
10.6.2 Red Hat/CentOS
Red Hat/CentOS systems deny access to unknown PAM service names by default. This is because the
other configuration in
/etc/pam.d/other contains only “deny” rules.
#%PAM-1.0 # The Red Hat/CentOS default "other" PAM service. auth required pam_deny.so account required pam_deny.so password required pam_deny.so session required pam_deny.so
The RStudio Connect RPM installs an
rstudio-connect PAM service at
/etc/pam.d/rstudio-connect. This service is configured to require a user-id greater than 500 and authenticates against local system accounts.
#%PAM-1.0 # The RStudio Connect default PAM service. auth requisite pam_succeed_if.so uid >= 500 quiet auth required pam_unix.so nodelay account required pam_unix.so
This default PAM service may not reflect the authentication behavior that you want for RStudio Connect. Feel free to customize this service for your organization.
10.6.3 Configuring a PAM service
This section may be helpful if your organization has different requirements from the default behavior of the
rstudio-connect PAM service name. Please consult with your PAM/systems administrator to be sure that the RStudio Connect PAM service configuration fits your needs.
If your system already has a PAM service (e.g.
/etc/pam.d/login) with the desired behavior, it may be enough to simply include that service from within the RStudio Connect service. For example:
# RStudio Connect PAM service that defers to the existing login service. @include login
You could also copy that existing service into the RStudio Connect service, meaning the copy can be changed and evolve independently from the source service.
$ sudo cp /etc/pam.d/login /etc/pam.d/rstudio-connect
Lastly, you could configure the
PAM.Service setting to reference that PAM service. This would be appropriate if you have a common
rstudio service that you use across all the RStudio products, for example.
[PAM] Service = rstudio
If you change the
PAM.Service setting from its default
rstudio-connect value, the PAM service defined in
/etc/pam.d/rstudio-connect will not be used.
10.6.4 PAM Credential Caching
Note: RStudio Connect’s PAM cache is encrypted and is not stored on disk. The credentials must expire after a certain period of time.
RStudio Connect can be configured to securely cache a user’s PAM credentials when they log in to RStudio Connect. This enables RStudio Connect to let users run R processes as their current UNIX account when the PAM profile requires a user’s credentials.
The following config settings are required for credential caching to be enabled:
[Applications] RunAsCurrentUser = true [PAM] UseSession = true ; Enable PAM sessions ForwardPassword = true ; Forward the current user's password into the PAM session PasswordLifetime = 12h ; Cache passwords for 12 hours after login
12h with the amount of time you would like credentials to be cached. Credential lifetime is counted from the moment the user logs into RStudio Connect. It is not tied to the user’s web session, except that logging in again will restart the timer for that user’s credentials.
Groups are not supported when using PAM authentication.
10.7 Proxied Authentication
RStudio Connect supports proxied authentication. This allows an external system to intercept requests and handle the authentication of users visiting the Connect dashboard or applications Connect is hosting.
10.7.1 How this Works
A service (like Apache, for example) runs as your customized authentication server. It is responsible for intercepting all requests to RStudio Connect and performing the required authentication and authorization. Requests from authenticated users will have a custom HTTP header added before the request is proxied through to RStudio Connect. That HTTP header contains the username of that visitor. RStudio Connect will take the value from the HTTP header and treat the current user as the username specified in the header.
We have no means of validating that this HTTP header was added by your authentication server and not by the user directly. So it is very important from a security perspective that the RStudio Connect server is properly firewalled off in your network and that all access to the Connect server is proxied through your authentication server.
The username HTTP header should never be set by the requester. In all cases, your authentication server should delete that header if it exists before authenticating the user and adding the header itself.
RStudio Connect does not currently support directing users to a login page when using proxied authentication. Therefore, we recommend that your proxy prevent anonymous access to RStudio Connect; only allow authenticated users.
10.7.2 Deployment from the RStudio IDE
Deploying from the RStudio IDE is a unique situation. The IDE uses an R package
rsconnect to obtain deployment credentials from RStudio Connect. Those credentials are used to sign deployment requests.
Deployment requests are signed with credentials obtained during an earlier, authenticated session, and should pass through your proxy without alteration.
The following three headers when used together identify deployment requests and should pass through your proxy without attempting to authenticate the user:
10.7.3 Configuring Proxied Authentication
To configure RStudio Connect to use proxied authentication, set
[Authentication] Provider = proxy
Proxied authentication requires that you set
Server.Address to point at your proxy server. If you do not configure
Server.Address, the browser may not have all its requests routed through your authenticating proxy. See Section 2.2.1 for more information about
[Server] Address = https://myproxy.company.com/
You can customize the name of the header that your authentication server will send upon a successful authentication. By default, this key name is
[ProxyAuth] UsernameHeader = X-Auth-Username
Groups are not supported when using proxied authentication.