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 6.1.
External authentication is available through the following integrations:
- LDAP and Active Directory (Section 6.2)
- OAuth 2.0 using Google Apps accounts (Section 6.3)
- PAM (Section 6.4)
- Proxied Authentication (Section 6.5)
Choose an appropriate authentication scheme for your organization by customizing the
Authentication.Provider property, detailed in Section 10.6.
Here is a partial configuration which chooses to use LDAP.
[Authentication] Provider = ldap
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
6.2 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. Groups are not yet supported.
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.
- A username or DN containing a forward slash (
/) is not supported.
6.2.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 10. 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.
6.2.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: email@example.com
More LDAP configuration scenarios can be found in Appendix 11.
6.2.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
TLSCACertificateFile 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.
TLSCACertificateFile = /etc/ssl/cert/ca.pem
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 (aka double bind), it is not required (aka 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 = firstname.lastname@example.org BindPassword = adminpassword # Example NT-style login BindDN = COMPANY\\admin # we use double slashes (\\) to character escape the last slash BindPassword = adminpassword
UserSearchBaseDN (required) is the starting point from which RStudio Connect will search for entries in your LDAP/AD server.
UserSearchBaseDN = dc=company,dc=com UserSearchBaseDN = ou=People,dc=company,dc=com
UserObjectClass is the
objectClass that a user in your LDAP/AD structure will have. Common examples of this are
inetOrgPerson. This is only required when the
UserSearchBaseDN location contains types of LDAP entries other than users (e.g. groups).
UserObjectClass = user UserObjectClass = posixAccount
UsernameAttribute (required) is the LDAP entry attribute that contains the username of a user.
UsernameAttribute = uid UsernameAttribute = sAMAccountName
UserFirstNameAttribute (required) is the LDAP entry attribute that contains the first name of a user.
UserFirstNameAttribute = givenName
UserLastNameAttribute (required) is the LDAP entry attribute that contains the last name of a user.
UserLastNameAttribute = sn
UserEmailAttribute (required) is the LDAP entry attribute that contains the email address of a user.
UserEmailAttribute = mail
6.3 OAuth2 (Google)
OAuth2 authentication is available to authenticate against Google’s OAuth service.
RStudio Connect will use OAuth2 authentication if the
Authentication.Provider setting has a value of
[Authentication] Provider = oauth2
Appendix 10.7 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 secret.
6.3.1 Obtaining a Client ID and Client Secret
These instructions tell you how to obtain an OAuth2 client id and secret. We recommend using a distinct configuration from other applications authentication with Google’s 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, click the link “Enable and manage APIs”. Locate the “Google+ API” and enable it.
- 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 URI”, put your RStudio Server with
- Click “Create”. Your client ID and client secret show now 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!
6.3.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 = email@example.com firstname.lastname@example.org
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
You can change the PAM service name used for authentication by customizing the
PAM.Service setting. The default PAM service name used by RStudio Connect 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.
RedHat and 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 # RedHat/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 # 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.
6.4.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
/etc/pam.d/rstudio-connect PAM service will not be used.
Groups are not supported when using PAM authentication.
6.5 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.
6.5.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.
6.5.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:
6.5.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.3.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.