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

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.6)
  • OAuth 2.0 using Google Apps accounts (Section 10.7)
  • PAM (Section 10.8)
  • Proxied Authentication (Section 10.9)

Customize the Authentication.Provider property with an authentication scheme appropriate for your organization. See Section A.10 for details

Here is a partial configuration which chooses to use LDAP.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authentication]
Provider = ldap

10.1 Changing Authentication Provider

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.1.1 Unsupported Authentication Changes

  • Changing from one authentication provider to another (for example, changing provider from password to LDAP) is NOT SUPPORTED.

Why? Users cannot log into accounts created with other authentication providers. The accounts under the previous authentication provider will be orphaned, including any administrator accounts.

  • Changing user UNIX accounts under PAM is NOT SUPPORTED.

Why? The user’s Unix account name is considered the source of truth for user identity. This means that a clustered configuration does not need to ensure usernames have the same UIDs on every node.

  • Changing X-Auth-Username responses for a user under Proxy auth is NOT SUPPORTED

Why? The X-Auth-Username response is considered the source of truth for user identity.

10.2 Session Management

Sessions are stored on the server in RStudio Connect. Encrypted session cookies stored only on the client are deprecated, as they provide inferior security.

The server will periodically check the data store for expired cookies and remove them. This happens once per hour by default, but is configurable using the Authentication.CookieSweepDuration configuration setting. This does not affect the lifetime of web sessions, which is controlled by the Authentication.Lifetime configuration setting.

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

By default, the LDAP, PAM, and Proxy authentication providers require that a valid username is received from the provider. LDAP additionally requires a valid user email. If the provider cannot resolve any of these, an error will be thrown.

Note that there is a known issue: if LDAP.UsernameAttribute is blank for the given LDAP credentials, the user will not be able to authenticate.

The LDAP, PAM, and Proxy authentication providers use relaxed username requirements. These providers permit any username, except the following prohibited usernames:

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

10.4 User Attribute Editability

Depending on your authentication provider, certain attributes of a user are editable and certain ones are not. Furthermore, who is able to make edits to which user can change depending on configuration.

10.4.1 Password

All user attributes are editable by either an administrator or by the user themselves. You can configure password authentication (via Password.UserInfoEditableBy) to allow only administrators to edit user attributes or allow both administrators to edit anyone’s attributes and users to edit their own attributes. It is recommended that if you set SelfRegistration = false, that you also configure UserInfoEditableBy to Admin. This is so users created by the administrator cannot be changed by non-administrators.

10.4.2 OAuth

For OAuth, first name, last name, and email address are provided by the provider. Therefore, it is not editable by any user. If you need to change/update this information, update your oauth provider and the changes will be synced into RStudio Connect on next user login.

Usernames are chosen by the logging in user at first login. Usernames may be subsequently edited by the user or an administrator.

10.4.3 LDAP

All user attributes are provided by the LDAP server(s). If you need to change user attributes in RStudio Connect, you can do this within the LDAP record and RStudio Connect will be updated on next user login.

Please be aware, that any changes to the value that uniquely identifies the user on LDAP will cause RStudio Connect to see it as a brand new user creating a new account and the individual will not be able to log into their old account.

The section 10.6 has more information on how to avoid such issues by using vendor-specific values to identify users.

Additionally, please refer to the appendix B for more information on using the usermanager CLI to repair users in the situation above.

10.4.4 Proxy

For proxy, first name, last name, and email address are user editable (since this information is not known by the provider). A user can edit their own attributes here, as well as an administrator.

Usernames are taken from the provider, therefore, is not editable. Changing the username given by the proxy will result in a new user being created in RStudio Connect.

10.4.5 PAM

First name, last name, and email addresses may be edited by the user or an administrator in PAM authentication mode. Usernames are not editable because they correspond to the UNIX account username.

If a user’s corresponding UNIX account username is changed, RStudio Connect will create a new account for that username the next time they log in.

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authentication]
Provider = password

10.6 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:

  • A user is uniquely identified by the attribute defined in LDAP.UniqueIdAttribute. This defaults to "DN" (Distinguished Name) which offers a broad compatibility with different LDAP products but has some known limitations. For information on how to configure this setting for your specific LDAP server, see 10.6.3.8
  • The same limitation applies to LDAP groups which use LDAP.GroupUniqueIdAttribute to define the attribute which uniquely identifies them, also with the default of "DN".
  • The following user information is required: first name, last name, email address, and username. Different LDAP/AD attributes may be used for each of these fields.
  • Changes to a user (e.g. their name, email address, or username) will not propagate to RStudio Connect until the next time the user logs in.
  • When using single bind, the DN of a user must contain their username ( i.e. must utilize the LDAP.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.Logging = true to any LDAP section in the configuration.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "any"]
Logging = true

10.6.1 Defining an LDAP or AD section

Start an LDAP or Active Directory configuration with a LDAP section header like the following:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "European AD Server"]
...

An LDAP or Active Directory configuration section header is always of the form [LDAP "EFFECTIVE NAME"]. The “effective name” is a name that is meaningful to your organization ("European AD Server" in the example).

RStudio Connect supports more than one LDAP/AD server through multiple, uniquely named LDAP configuration sections. Other complex LDAP/AD configurations can also be achieved by using multiple LDAP sections.

Make sure that each LDAP configuration section has a unique effective name. If multiple LDAP sections have the same name, they will be combined as described in Appendix A.

The LDAP section name is treated case sensitively.

Here is a sample configuration using two LDAP sections.

; /etc/rstudio-connect/rstudio-connect.gcfg
[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.6.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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample OpenLDAP Configuration"]
ServerAddress = 127.0.0.1:389
BindDN = "cn=admin,dc=example-openldap"
BindPassword = "XXXXXXXX"
UserSearchBaseDN = "ou=People,dc=example-openldap"
UniqueIdAttribute = "entryUUID"
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
entryUUID: c1afa3d6-d688-1037-99f0-d7682e3458da

More LDAP configuration scenarios can be found in Appendix D.

10.6.3 LDAP or AD Configuration Settings

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
ServerAddress = 127.0.0.1:389
ServerAddress = ldap.company.com:389
ServerAddress = ldaps.company.com:636
ServerAddress = private.internal.local:7554

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
TLS = true
TLS = false

10.6.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 “LDAPS” or “Opportunistic TLS”. The default value for this is false. This cannot be enabled if TLS is true.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Debug]
Log = ldap

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
TLSCACertificate= /etc/ssl/cert/ca.pem

10.6.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 man-in-the-middle attacks, but is required if, for example, your server uses a self-signed certificate. The default value is false.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
ServerTLSInsecure = true
ServerTLSInsecure = false

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

Quote passwords and DNs that contain a literal double-quote (") or one of the ; or # comment characters.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
; Example DN
BindDN = uid=john,ou=People,dc=company,dc=com
BindPassword = "johnpassword"
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
; Example UPN
BindDN = admin@company.com
BindPassword = "adminpassword"
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
; Example NT-style login
BindDN = COMPANY\\admin  # we use double slashes (\\) to character escape the last slash
BindPassword = "adminpassword"

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
AnonymousBind = true

10.6.3.8 UniqueIdAttribute

UniqueIdAttribute (optional, default "DN") is the vendor-specific object attribute present for all users which has a unique value that identities the object persistently. Commonly used attributes include:

  • objectGUID (Microsoft AD)
  • entryUUID (OpenLDAP)
  • orclGuid (Oracle OID)
  • ibm-entryUUID (IBM RACF)
  • GUID (Novell eDirectory)

Please refer to your LDAP vendor documentation for the correct value.

WARNING: any change to this setting automatically invalidate all existing users. RStudio Connect will try to detect this and it will not start if problems are found. Before starting up RStudio Connect with the new configuration, all users must be adjusted to use the updated attribute value via the usermanager CLI: B.1

Note: The use of the default value of "DN" is not recommended and existing installations should use a different value if possible. RStudio Connect will issue a warning on startup if this condition is detected. The Distinguished Name (DN) is not a persistent value in LDAP/AD and it may change in certain situations. RStudio Connect will no longer be able to refer to a user once their DN changes. You can repair an affected user by updating the DN via the usermanager CLI: B.1

10.6.3.9 UserSearchBaseDN

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserSearchBaseDN = dc=company,dc=com
UserSearchBaseDN = ou=People,dc=company,dc=com

10.6.3.10 UserObjectClass

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

UserObjectClass is used to define UserFilterBase if that property is not explicitly configured. Either UserObjectClass or UserFilterBase must be defined. If both have values, only UserFilterBase will be used.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserObjectClass = user
UserObjectClass = posixAccount

10.6.3.11 UserFilterBase

The UserFilterBase attribute allows more flexible when searching for user objects in complicated LDAP hierarchies.

Either UserObjectClass or UserFilterBase must be defined. If UserFilterBase is unset, it is given a default value of objectClass={UserObjectClass}.

If users are identified by two separate objectClass values, you might use the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserFilterBase = &(objectClass=user)(objectClass=statistician)

You can disqualify an objectClass value with the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserFilterBase = &(objectClass=user)(!(objectClass=computer))

10.6.3.12 UsernameAttribute

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UsernameAttribute = uid
UsernameAttribute = sAMAccountName

10.6.3.13 UserFirstNameAttribute

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserFirstNameAttribute = givenName

10.6.3.14 UserLastNameAttribute

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserLastNameAttribute = sn

10.6.3.15 UserEmailAttribute

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserEmailAttribute = mail

10.6.3.16 PermittedLoginGroup

PermittedLoginGroup 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

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
PermittedLoginGroup = cn=admins,ou=group,dc=company,dc=com
PermittedLoginGroup = cn=scientists,ou=group,dc=company,dc=com

10.6.3.17 GroupUniqueIdAttribute

GroupUniqueIdAttribute (optional, default "DN") is the vendor-specific object attribute present for all groups which has a unique value that identities the object persistently. Please refer to your LDAP vendor documentation for the correct value. In general, users and groups use the same value. See 10.6.3.8

WARNING: any change to this setting automatically invalidate all existing groups. RStudio Connect will try to detect this and it will not start if problems are found. Before starting up RStudio Connect with the new configuration, all groups must be adjusted to use the updated attribute value via the usermanager CLI: B.1

Note: The use of the default value of "DN" is not recommended and existing installations should use a different value if possible. RStudio Connect will issue a warning on startup if this condition is detected. The Distinguished Name (DN) is not a persistent value in LDAP/AD and it may change in certain situations. RStudio Connect will no longer be able to refer to a group once their DN changes. You can repair an affected groups by updating the DN via the usermanager CLI: B.1

10.6.3.18 GroupObjectClass

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

GroupObjectClass is used to define GroupFilterBase if that property is not explicitly configured. Either GroupObjectClass or GroupFilterBase may be defined. If both have values, only GroupFilterBase will be used.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupObjectClass = group
GroupObjectClass = posixGroup

10.6.3.19 GroupFilterBase

The GroupFilterBase attribute allows more flexible when searching for group objects in complicated LDAP hierarchies.

Either GroupObjectClass or GroupFilterBase may be defined. If GroupFilterBase is unset, it is given a default value of objectClass={GroupObjectClass}.

If groups are identified by two separate objectClass values, you might use the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupFilterBase = &(objectClass=group)(objectClass=club)

You can disqualify an objectClass value with the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupFilterBase = &(objectClass=group)(!(objectClass=flock))

10.6.3.20 GroupNameAttribute

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupNameAttribute = cn
GroupNameAttribute = sAMAccountName

10.6.3.21 GroupSearchBaseDN

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupSearchBaseDN = dc=company,dc=com
GroupSearchBaseDN = ou=Groups,dc=company,dc=com

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authentication]
Provider = oauth2

Appendix A.12 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.7.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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
ClientId = <CLIENT ID>
ClientSecret = <CLIENT SECRET>

With ClientId and either ClientSecret or ClientSecretFile configured, you can use your Google Apps account to sign into RStudio Connect!

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[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.7.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.8 PAM

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authentication]
Provider = pam

See Section 12.7 for information about using PAM sessions when launching processes associated with deployed content.

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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[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.7 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 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 Applications.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.8.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.8.2 Red Hat/CentOS/SUSE

Red Hat/CentOS/SUSE systems may 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.8.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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[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.8.4 Groups

Groups are not supported when using PAM authentication.

10.9 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.9.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. 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.9.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. The minimum required version of rsconnect for proxy authentication is 0.8.7.

Deployment requests are signed with credentials obtained during an earlier, authenticated session, and should pass through your proxy without alteration.

The X-Auth-Token header identifies deployment requests. When the X-Auth-Token header is present, the request should be allowed to pass through your proxy without attempting to authenticate the user. Further, the following three headers are used in the deployment process and should not be edited or removed by your proxy.

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

Additionally, the Authorization header should allow traffic to pass through the proxy without attempting to authenticate the user when:

  • The RStudio Connect Server API is being used.
  • RStudio Connect is serving hosted APIs (i.e. Plumber, TensorFlow, etc.)

Note: Look for a value containing Key followed by the API key for a more specific match of the Authorization header used by RStudio Connect.

10.9.3 Example Proxy Configuration

The following examples demonstrate how to intercept and re-route unauthenticated requests to RStudio Connect, which is served via reverse-proxy at /rsconnect. The examples assume an authentication server is running at /auth which, upon successful authentication, will set a HTTP-only cookie named verified-user containing the username of the authenticated user and redirect the user back to RStudio Connect via the URL specified in the url query parameter.

Nginx configuration:

map $http_upgrade $connection_upgrade {
  default upgrade;
  ""      close;
}

map $http_cookie $auth_username {
  default "";
  "~*verified-user=(?<username>[^;]+)" "$username";
}

map "$http_x_auth_token" $has_token {
    default "";
    "~.+" "token";
}

map "$http_authorization" $has_key {
    default "";
    "~Key .+" "key";
}

map "$auth_username:$has_token:$has_key" $requires_auth {
  default 0;
  "::" 1;
}

server {
  listen 80 default_server;

  location /rsconnect/ {

    if ($requires_auth = 1) {
      return 307 $scheme://$host:$server_port/auth/login?url=$request_uri;
    }

    rewrite                    ^/rsconnect/(.*)$ /$1 break;
    proxy_pass                 http://rstudio-connect-host:3939;
    proxy_redirect             / /rsconnect/;
    proxy_pass_request_headers on;
    proxy_connect_timeout      5;
    proxy_http_version         1.1;
    proxy_buffering            off; # Required for XHR-streaming

    proxy_set_header           Upgrade $http_upgrade;
    proxy_set_header           Connection $connection_upgrade;
    proxy_set_header           X-RSC-Request $scheme://$host:$server_port$request_uri;
    proxy_set_header           X-Auth-Username $auth_username;
  }
}

Apache configuration:

RewriteEngine on
ProxyPreserveHost on

<VirtualHost *:80>
  SetEnvIf Cookie "verified-user=([^;]+)" AuthUsername=$1
  <If "%{REQUEST_URI} !~ m#^/auth# && -z env('AuthUsername') && -z %{HTTP:X-Auth-Token} && %{HTTP:Authorization} !~ /Key .+/">
    Redirect 307 "%{REQUEST_SCHEME}://%{HTTP_HOST}/auth/login?url=%{REQUEST_URI}"
  </If>

  <Location /rsconnect/>
    ProxyPass http://rstudio-connect-host:3939/ connectiontimeout=5
    ProxyPassReverse /

    RequestHeader set X-RSC-Request "%{REQUEST_SCHEME}s://%{HTTP_HOST}s%{REQUEST_URI}s"
    <If "-n env('AuthUsername')">
      RequestHeader set X-Auth-Username "%{AuthUsername}e"
    </If>
    <Else>
      RequestHeader unset X-Auth-Username
    </Else>

    RewriteCond %{HTTP:Upgrade} =websocket
    RewriteRule /rsconnect/(.*) ws://rstudio-connect-host:3939/$1 [P,L]
    RewriteCond %{HTTP:Upgrade} !=websocket
    RewriteRule /rsconnect/(.*) http://rstudio-connect-host:3939/$1 [P,L]
  </Location>
</VirtualHost>

10.9.4 Configuring Proxied Authentication

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[ProxyAuth]
UsernameHeader = X-Auth-Username

10.9.5 Troubleshooting Proxied Authentication

When attempting to troubleshoot a problem relating to proxied authentication, you can enable more verbose logging by adding ProxyAuth.Logging = true to the configuration. All the contents of headers and the names of the cookies received with the authentication request will be logged. Cookies and headers used by RStudio Connect will be logged as <internal>. External cookie values will be logged as <redacted>. If an external cookie comes without a value it will be logged as <empty>.

  • “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.
  • Attempts to deploy to RStudio Connect from the IDE fail because users are redirected to a Single Sign-On page.
  1. Ensure that the proxy is configured to pass through all requests that set the X-Auth-Token header.
  2. Ensure that the user has the rsconnect package with at least version 0.8.7 installed. If not, and if the package isn’t available from CRAN, it may be installed from the R console using devtools::install_github('rstudio/rsconnect')

10.9.6 Groups

Groups are not supported when using proxied authentication.