10 Authentication

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)

Customize the 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.

See A.9, A.10, and A.11 for usage of the RequireExternalUsernames setting.

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:

  • connect
  • apps
  • users
  • groups
  • setpassword
  • user-completion
  • confirm
  • recent
  • reports
  • plots
  • unpublished
  • settings
  • metrics
  • tokens
  • help
  • login
  • welcome
  • register
  • resetpassword
  • content

10.3 Password

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=com but their actual username is stored in the uid or SAMAccountName LDAP 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 ldap to 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: john@example.com

More LDAP configuration scenarios can be found in Appendix D.

10.4.3 LDAP or AD Configuration Settings

10.4.3.1 ServerAddress

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 389 or 636 (for SSL). But you can specify any port that fits your environment.

Examples

ServerAddress = 127.0.0.1:389
ServerAddress = ldap.company.com:389
ServerAddress = ldaps.company.com:636
ServerAddress = private.internal.local:7554

10.4.3.2 TLS

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 StartTLS is true.

Examples

TLS = true
TLS = false

10.4.3.3 StartTLS

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 TLS is true.

Examples

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

10.4.3.4 TLSCACertificate

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.

Examples

TLSCACertificate= /etc/ssl/cert/ca.pem

10.4.3.5 ServerTLSInsecure

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 false.

Examples

ServerTLSInsecure = true
ServerTLSInsecure = false

10.4.3.6 BindDN and BindPassword

BindDN and 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.

The BindDN can be a DN, UPN, or NT-style login.

Examples

# Example DN
BindDN = uid=john,ou=People,dc=company,dc=com
BindPassword = johnpassword

# Example UPN
BindDN = admin@company.com
BindPassword = adminpassword

# Example NT-style login
BindDN = COMPANY\\admin  # we use double slashes (\\) to character escape the last slash
BindPassword = adminpassword

10.4.3.7 AnonymousBind

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 BindDN and BindPassword.

For this to work properly, your LDAP server must allow anonymous binds to search and view all pertinent groups, group memberships, and users.

Examples

AnonymousBind = true

10.4.3.8 UserSearchBaseDN

UserSearchBaseDN (required) is the starting point from which RStudio Connect will search for user entries in your LDAP/AD server.

Examples

UserSearchBaseDN = dc=company,dc=com
UserSearchBaseDN = ou=People,dc=company,dc=com

10.4.3.9 UserObjectClass

UserObjectClass (required) is the objectClass that a user in your LDAP/AD structure will have. Common examples of this are user, posixAccount, organizationalPerson, person, and inetOrgPerson.

Examples

UserObjectClass = user
UserObjectClass = posixAccount

10.4.3.10 UsernameAttribute

UsernameAttribute (required, case-sensitive) is the LDAP entry attribute that contains the username of a user.

Examples

UsernameAttribute = uid
UsernameAttribute = sAMAccountName

10.4.3.11 UserFirstNameAttribute

UserFirstNameAttribute (required, case-sensitive) is the LDAP entry attribute that contains the first name of a user.

Examples

UserFirstNameAttribute = givenName

10.4.3.12 UserLastNameAttribute

UserLastNameAttribute (required, case-sensitive) is the LDAP entry attribute that contains the last name of a user.

Examples

UserLastNameAttribute = sn

10.4.3.13 UserEmailAttribute

UserEmailAttribute (required, case-sensitive) is the LDAP entry attribute that contains the email address of a user.

Examples

UserEmailAttribute = mail

10.4.3.14 WhitelistedLoginGroup

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.

Examples

WhitelistedLoginGroup = cn=admins,ou=group,dc=company,dc=com
WhitelistedLoginGroup = cn=scientists,ou=group,dc=company,dc=com

10.4.3.15 GroupObjectClass

GroupUserObjectClass is the objectClass that a group in your LDAP/AD structure will have. Common examples of this are group, and posixGroup.

Examples

GroupObjectClass = group
GroupObjectClass = posixGroup

10.4.3.16 GroupNameAttribute

GroupNameAttribute (case-sensitive) is the LDAP entry attribute that contains the name of a group.

Examples

GroupNameAttribute = cn
GroupNameAttribute = sAMAccountName

10.4.3.17 GroupSearchBaseDN

GroupSearchBaseDN is the starting point from which RStudio Connect will search for group entries in your LDAP/AD server.

Examples

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 oauth2.

[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.

  1. Visit the Google Developers Console and create a new project. Give it a name of your choosing, such as “rstudio-connect”.
  2. Once the project is created, locate and enable the “Google+ API”.
  3. In the left navigation window, click on “Credentials”, then goto the “OAuth consent screen” tab, fill in the information requested and click “Save”.
  4. Once again, click “Credentials” in the left navigation window. Then click the dropdown button “New credentials”, then “OAuth client ID”.
  5. For “Application Type”, select “Web Application”. Then give your client ID a descriptive name. For “Authorized JavaScript origins”, enter your RStudio Server URL (i.e. https://HOST:PORT). For “Authorized redirect URIs”, use your RStudio Connect server address with /__login__/callback (i.e. https://HOST:PORT/__login__/callback).
  6. 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>

With DiscoveryEndpoint, ClientId and either ClientSecret or 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.

The 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 = jdoe@company.com asmith@subsidiary.com

It is important to understand how the AllowedDomains and AllowedEmails properties interact.

If only AllowedDomains is configured, only email addresses with a listed domain will be permitted access.

If only AllowedEmails is configured, only listed email addresses will be permitted access.

When both AllowedDomains and AllowedEmails are specified, email addresses given in AllowedEmails are permitted access in addition to email addresses with a domain listed in AllowedDomains.

10.5.3 Searches

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 subsidiary.com.

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.

10.6 PAM

RStudio Connect can use PAM for user authentication. PAM authentication is used if the Authentication.Provider setting has a value of pam.

[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 rstudio-connect.

[PAM]
Service = rstudio-connect

Note that there are three types of PAM service that can be configured in the PAM configuration section (See Section 12.5 for more information):

  • PAM.Service - The PAM service used for authenticating users when logging in.
  • PAM.SessionService - When PAM.UseSession is enabled, the PAM service used for running basic R processes either as the default user or as an arbitrary user. Should not require a password.
  • PAM.AuthenticatedSessionService - The PAM service used for running processes as the currently logged-in user with the user’s password. Requires PAM.UseSession, PAM.ForwardPassword, and PAM.RunAsCurrentUser to be enabled. Useful for Kerberos configurations.

We assume that RStudio Connect is configured to use the rstudio-connect PAM service name for authentication in the examples that follow.

10.6.1 Ubuntu

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 /etc/pam.d/other.

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

If the 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 Groups

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.

Important Note

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 will return a generic authentication failure if duplicate authentication headers are provided.

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:

  • X-Auth-Token
  • X-Auth-Signature
  • X-Content-Checksum

10.7.3 Configuring Proxied Authentication

To configure RStudio Connect to use proxied authentication, set Authentication.Provider to proxy.

[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.

[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 X-Auth-Username.

[ProxyAuth]
UsernameHeader = X-Auth-Username

10.7.4 Troubleshooting Proxied Authentication

  • “Rejected insecure proxy authentication attempt” appears in the server logs, users cannot log in
  1. Ensure that the proxy is configured to delete the username header from incoming requests (X-Auth-Username by default)
  2. Ensure that users are connecting to RStudio Connect by its proxy, and not directly to the server. As noted above, your network should be configured to make non-proxied connections to RStudio Connect impossible.

10.7.5 Groups

Groups are not supported when using proxied authentication.