11 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 11.5.

When signing into RStudio Connect, a browser cookie is used to keep the user logged in. See section 9.2.2 for details about the default session lifetime and how to change it.

External authentication is available through the following integrations:

LDAP and Active Directory (Section 11.6)
SAML (Section 11.7)
OAuth 2.0 using Google Apps accounts (Section 11.8)
PAM (Section 11.9)
Proxied Authentication (Section 11.10)

Customize the Authentication.Provider property with an authentication scheme appropriate for your organization.

Here is a partial configuration which chooses to use LDAP.

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

11.1 Changing Authentication Provider

The decision to change which authentication provider is configured for RStudio Connect should not be entered into lightly. Doing so in an inappropriate way can lead to loss of access to a user’s content, subscriptions and other assets (note that only the access to the assets is affected; the assets themselves will still exist).

There are use cases, however, where changing the authentication provider is necessary. One of the most common ones is when RStudio Connect has been using the default password provider for a proof of concept and needs to be switched to a corporate standard like LDAP once it has been decided to make use of RStudio Connect in a production environment.

If maintaining existing content is not important, the simplest approach will be to completely purge and reinstall RStudio Connect. See Section 5.5 for instructions.

11.1.1 Uniquely Identifying Users

Among the data that RStudio Connect maintains about a user is a Unique ID. Even though the username (the identifier used for logging in and displayed in the Connect dashboard) must also be unique, the Unique ID is the real marker for uniquely identifying a user. All authentication providers require some form of this. Some, like the default password provider, invent their own when users are created. External providers (proxy, LDAP, etc.) generally have their own notion of this. LDAP, for example, uses the distinguished name (or DN) by default as a Unique ID, even though the recommendation is using values that don’t change over time, usually vendor-specific (such as objectGUID for AD or entryUUID for OpenLDAP).

The success of changing the authentication provider is completely dependent on how these Unique IDs are mapped from the old provider to the new one. There are two approaches to consider when changing the provider, the distinguishing point being whether a second user record gets created the first time a user logs in with the new auth provider or, similarly, if there is a reason for using the RStudio Connect Server API to create new user records ahead of time.

Avoiding this user creation is the most straightforward choice, but will require the most knowledge about what the new provider will use for the user’s Unique ID. If this is discoverable ahead of time, these steps may be followed:

Stop RStudio Connect.
Use the list command of the usermanager tool to discover the identifier for each user in RStudio Connect. The GUID is the recommended ID to use.
Using tools available from the source behind the new authentication provider, such as LDAP, determine the Unique ID that the provider will use for each user.
For each user, use the user’s RStudio Connect identifier to assign the new Unique ID to the user using the usermanager tool. For example,
```
sudo /opt/rstudio-connect/bin/usermanager alter --user-guid <guid> \
   --new-unique-id <provider-unique-id>
```
Reconfigure RStudio Connect to use the new authentication provider.
Restart RStudio Connect.

These steps are generic and may need adjustment to fit with your situation. They can be followed for performing a bulk update of multiple users or for one user at a time. Since the usermanager tool can only be run while RStudio Connect is not, doing bulk updates is recommended to minimize downtime.

Note: The Unique ID is stored as it comes from the authentication provider for SAML, OAuth2 and for LDAP using Distinguished Name (DN). LDAP uses a base64-encoded value when not using DN and since these may sent to RStudio Connect as binary values. Proxied authentication when relying on headers for the Unique ID instead of usernames also stores Unique ID as a base64-encoded value, even when the header value is plain text. Currently, Password, PAM and Proxied authentication relying on usernames use internal formats. If you are migration from other providers to these three, this first approach is not recommended.

If determining the Unique ID that the new authentication provider will use for a user is problematic, there are two other alternatives.

First, once RStudio Connect has been reconfigured with the new authentication provider, use the RStudio Connect Server API to create new user records yourself. For most authentication providers, the Unique ID will be properly determined so you don’t have to work out what it is. Then, you can transfer all the assets from the user’s old record to the new one with the usermanager tool. Doing this has the advantage of making the user’s assets immediately available upon their first login under the new authentication provider.

Note: Be aware that usernames are unique in RStudio Connect with Password, PAM, OAuth2 and Proxied authentication (without ProxyAuth.UniqueIdHeader. If you are migrating from LDAP or SAML to Password, PAM or Proxied authentication and the usernames of the accounts being created are the same as the ones already in RStudio Connect for the authentication an additional step is required first. The existing users must have their usernames modified. One possibility is adding a suffix (i.e. _old) before the migration. This can be done via the usermanager tool or, if usernames are currently editable with your current authentication provider settings, also via Connect Server API. If you are migrating to LDAP, SAML or Proxied authentication (with ProxyAuth.UniqueIdHeader no user renaming is required because the user identity is based on the Unique ID and duplicate usernames are allowed.

Or, you can require that the user log in to RStudio Connect under the new authentication provider. This will create a new user record to which you can manually transfer all the user’s assets from the old record. As noted above, if the username is expected to be the same for the new user, modifying the existing user’s username may be needed.

Note: If you have configured RStudio Connect so that new user records are not automatically created, you will need to use the API to create new user records. See the RegisterOnFirstLogin configuration option under any provider, such as OAuth2.RegisterOnFirstLogin

To use these approaches, these steps may be followed:

Stop RStudio Connect.
Reconfigure RStudio Connect to use the new authentication provider.
Restart RStudio Connect.
If necessary modify the existing user’s username to avoid duplicates.
Either create the new user record via the RStudio Connect Server API or require the user to log in.
Stop RStudio Connect.
Use the list command of the usermanager tool to discover the identifier for the old record for the user in RStudio Connect. The GUID is the recommended ID to use.
Use the same command to discover the identifier for the new record for the user. If you used the API to create the user, the response to the create endpoint will contain the GUID.
Use the transfer command of the usermanager tool to transfer all user assets from the old user identifier to the new one. You may optionally delete the old RStudio Connect user data as part of the transfer. For example,
```
sudo /opt/rstudio-connect/bin/usermanager transfer --source-guid <old-guid> \
   --target-guid <new-guid> --memberships --permissions --api-keys --delete
```
Restart RStudio Connect.

Again, these steps are generic and may need adjustment to fit with your situation. Also, you may want to update more than one user at a time here to minimize downtime.

See Appendix B for more information on using the usermanager CLI to manage users.

11.1.2 Updating Groups

LDAP and Proxied authentication providers can manage their own groups automatically. When this option is used the groups created in RStudio Connect do not have owners.

When switching to another authentication provider that requires users to manage groups either manually or via the Connect Server API these groups without owners will not be fully effective. For example, group members cannot be manually added or removed if the groups was previously managed by the authentication provider.

RStudio Connect will issue a warning on startup if the ownership of the existing groups does not match the configuration of the current authentication provider. Additionally, the Connect dashboard will label these groups as managed by the provider.

The opposite is also true. Groups always have owners when created under Password, PAM, SAML, OAuth2 and Proxied authentication with automatic group provisioning disabled and these groups will not work with the LDAP provider or Proxied authentication with group provisioning enabled.

In the case above a warning will be issued since the Connect dashboard does not support manual management of groups managed by the authentication providers.

In these situations, either the group needs to be removed or the group ownership needs to be adjusted. This can be done with the usermanager CLI tool with the alter command using the --group-owner switch. Groups themselves can be removed via the Connect dashboard (if not managed by users), via the Connect Server API or via the usermanager CLI tool with the delete command. See B.3.

The goal is that all groups automatically provisioned should be assigned an owner if you intend to manage them in RStudio Connect. Conversely if you intend to have all groups managed by the authentication provider their owners should be removed. Also, you should remove any groups that do not make sense in the new configuration.

Note: In addition to group ownership switching authentication providers may also require adjustments to the Unique ID as done for users. This is true when switching from any other authentication provider to use LDAP when preserving the groups.

There are situations where a new authentication provider brings its own groups and the existing groups have no function other than their association to content. It is possible to leverage the usermanager CLI tool with the transfer command to transfer all access to content for one group to a different group. Group members can also be transferred using this option but only for groups managed by users. See B.3 for more details.

11.1.3 Unsupported Authentication Changes

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.

So, for example, if a user had the Unix account jim but now has the account james, RStudio will see this as a new user. You would need to use the usermanager transfer command to move everything from jim to james in this case.
Changing X-Auth-Username responses for a user under Proxied authentication is NOT SUPPORTED with one exception.

Why? The X-Auth-Username response is considered the source of truth for user identity. To be able to update usernames without creating new ones, an alternative and persistent identification must be provided. By using ProxyAuth.UniqueIdHeader it is possible to send a user identity to RStudio Connect which is separate from the username.

Note: Any existing users MUST be updated to have the new identity before ProxyAuth.UniqueIdHeader is changed or configured for the first time. Use the usermanager CLI tool to alter user identity.

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

11.3 Username requirements

When using the built-in Password authentication, users are required to choose a valid and unique 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.

On OAuth2, a unique username is generated based on the user’s email address using the rules above during the first login. These usernames can be modified.

By default LDAP and SAML usernames don’t need to be unique. That’s because multiple users with the same username may exist in large enterprise deployments (for example, two users may share a last name and first name initials). Proxied authentication can also be configured to allow non-unique usernames. PAM usernames are always required and unique. LDAP usernames are always required.

SAML and Proxied authentication can be configured to not require usernames. In this case, similar to OAuth2, an editable unique username will be generated based on the user’s email address, which becomes required at that point.

When the username is expected to be returned by the authentication provider but it is either missing or blank, the user will not be able to authenticate.

The LDAP, PAM, SAML, and Proxied authentication providers, when not generating usernames from an email, 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

See more details about usernames for each provider in 12.2.

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

11.4.1 Password (Built-in) Authentication

RStudio Connect considers all user attributes editable. The setting Authorization.UserInfoEditableBy has a default value of AdminAndSelf, permitting users and administrators to manage these user profile attributes. Configure Authorization.UserInfoEditableBy with Admin if profile editing should be restricted to administrators. It is recommended that if you disable Password.SelfRegistration with a value of false, that you also set Authorization.UserInfoEditableBy to Admin. A value of Admin means users created by the administrator cannot be changed by non-administrators.

11.4.2 OAuth2 (Google Apps with OpenID Connect)

For OAuth2, 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 OAuth2 provider and the changes will be synced into RStudio Connect on next user login.

Usernames are derived from the email address (without the domain) at the first login or if the user is added to content as a collaborator or a viewer before the first login in RStudio Connect. Duplicate or prohibited usernames have a sequence number suffix added. See more about usernames in 12.2.

The setting Authorization.UserInfoEditableBy controls whether or not your users will be permitted to manage their username and role. The default configuration has Authorization.UserInfoEditableBy with a value of AdminAndSelf, permitting users and administrators to manage these user profile attributes. A value of Admin permits only administrators to edit username and role.

It is recommended that if you disable OAuth2.RegisterOnFirstLogin with a value of false, that you also configure Authorization.UserInfoEditableBy to Admin. A value of Admin means that users created by the administrator, or in some cases a publisher, cannot be changed by non-administrators.

11.4.3 LDAP or Active Directory

A username is the primary means of authentication and therefore it is not editable.

The user’s first name, last name, and email address are considered editable only if not configured to be set by the provider. The setting Authorization.UserInfoEditableBy has a default value of AdminAndSelf, permitting users and administrators to manage these user profile attributes. Configure Authorization.UserInfoEditableBy with Admin if profile editing should be restricted to administrators.

The user attributes configured to be set by the provider are updated in RStudio Connect during every new user login.

It is recommended that if you disable LDAP.RegisterOnFirstLogin with a value of false, that you also configure Authorization.UserInfoEditableBy to Admin. A value of Admin means that users created by the administrator, or in some cases a publisher, cannot be changed by non-administrators.

Usernames in LDAP do not need to be unique. See more about usernames in 12.2.

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

11.4.4 SAML

The Unique ID of a user requires a mapping to either the Name ID of the SAML subject or to an Identity Provider (or IdP) assertion attribute and, as such, is not editable in RStudio Connect. Please be aware that any changes to this value that uniquely identifies the user in the SAML IdP will cause RStudio Connect to see it as a brand new user, thus creating a new account, and that the individual will not be able to log into their old account.

Which other user fields are editable is based on which fields are mapped from SAML assertion attributes. If a mapping exists for a field (username, first or last name, or email), it is considered managed by the SAML IdP. In that case, they will not be editable within RStudio Connect; changes to those fields should be made in the IdP; they will be correctly propagated to RStudio Connect the next time the user logs in.

Usernames in SAML may or may not be unique depending on the attribute mapping. See more about usernames in 12.2.

For fields with no attribute mapping, the Authorization.UserInfoEditableBy will control who can edit them. That option has a default value of AdminAndSelf, permitting users and administrators to manage these user profile attributes. Configure Authorization.UserInfoEditableBy with Admin if profile editing should be restricted to administrators.

11.4.5 Proxied Authentication

The user’s first name, last name, and email address are considered editable only if not provided by the proxy via configured headers. The setting Authorization.UserInfoEditableBy has a default value of AdminAndSelf, permitting users and administrators to manage these user profile attributes. Configure Authorization.UserInfoEditableBy with Admin if profile editing should be restricted to administrators.

It is recommended that if you disable ProxyAuth.RegisterOnFirstLogin with a value of false, that you also configure Authorization.UserInfoEditableBy to Admin. A value of Admin means that users created via the API by the administrator cannot be changed by non-administrators.

A username provided by the authenticating proxy as the primary means of identification for a given user and therefore it is not editable. In this situation, changing the username given by the proxy will result in a new user being created in RStudio Connect the next time the user logs in.

Alternatively, the authenticating proxy can provide a user identification separate from the username. Use the setting ProxyAuth.UniqueIdHeader for that purpose. The proxy can supply a different username in this situation, as long as the user identification remains the same over time. Even in this scenario the username is still not editable since the proxy is responsible for always providing a username.

Usernames in Proxied authentication may or may not be unique depending on the configuration. See more about usernames in 12.2.

11.4.6 PAM

RStudio Connect is always supplied with a username corresponding to the UNIX account username and therefore it is not editable. Changing the username of the UNIX account will result in a new user being created in RStudio Connect the next time the user logs in. See more about usernames in 12.2.

The user’s first name, last name, and email address are not provided by the hosting system and are considered editable. The setting Authorization.UserInfoEditableBy has a default value of AdminAndSelf, permitting users and administrators to manage these user profile attributes. Configure Authorization.UserInfoEditableBy with Admin if profile editing should be restricted to administrators.

It is recommended that if you disable PAM.RegisterOnFirstLogin with a value of false, that you also configure Authorization.UserInfoEditableBy to Admin. A value of Admin means that users created via the API by the administrator cannot be changed by non-administrators.

11.5 Password (Built-in) Authentication

Password authentication is the default authentication provider used by RStudio Connect. It uses local user accounts backed by the RStudio Connect database and is not integrated with any external, third-party authentication services.

Users will be able to create accounts when they first visit the system and will provide profile details, like username, name and email, at that time. An administrator will also be able to create new accounts. The first user that logs in automatically becomes an administrator.

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

11.5.1 Groups

Groups are supported when using Password authentication. They can be managed manually in the Connect dashboard or via the Connect Server API.

11.5.2 Limitations to Remember

Using password authentication makes it easy to get RStudio Connect up and running quickly but is really only appropriate when using RStudio Connect in one of these situations:

A demonstration or proof-of-concept in which RStudio Connect is being evaluated or explored.
Training users to use RStudio Connect.
Using RStudio Connect to do some small-scale testing.
A small group of users without, or isolated from, a centralized IT system.

11.5.3 Security Considerations

So far as it goes, the password authentication provider follows proper security policies but there are limitations to be aware of.

11.5.3.1 Acceptable Passwords

Passwords must be at least 6 characters long. Use the Password.MinimumScore configuration option to set a minimum complexity score for new passwords. The minimum score must be a number between 0 (the default) and 4. Any other value will prevent the RStudio Connect server from starting. A value of 0 will allow for any password, so long as the length requirement is met. A value of 1 will disallow the most obvious bad passwords, such as password, dates, the user’s email and so on. The higher the value, the more complex, and therefore secure, new passwords must be.

Note: Making the minimum score higher will not affect existing passwords; it will only affect new ones, either for new users or when a user changes his password.

11.5.3.2 Exceptions

It is important to remember that there are several additional security policies that the password authentication provider does not support. For example, the provider does not:

provide for password expiration,
provide automatic user lockout on multiple login failures,
enforce any specific limits on classes of characters.

Note that although no specific classes of characters can be specified as required (i.e., passwords must contain upper/lower case letters, digits, symbols, etc.), the more combinations of character types that are present in a password, the higher its score will be. So, requiring a higher minimum score will inherently require more variety in character types.

If your security needs require more fully fledged authentication capabilities, you will need to use an alternate authentication provider such as PAM, OAuth2, LDAP, SAML or Proxied authentication.

11.5.4 Support for Administrators

Administrators can create accounts directly in the RStudio Connect dashboard. Similar to to when users sign up for a new account, a confirmation email will be sent to the user.

In the case the user does not receive the confirmation email, the administrator can visit the user profile page under the “People” tab and resend this email. For existing users, the administrator can also send a password reset email from the same location.

11.5.5 Without Email Sending

Using password authentication without configuring email sending imposes limited functionality and reduced security. Because we cannot rely on emails for new user account confirmations and password reset requests the alternative is trusting on a RStudio Connect administrator to be a intermediary in these operations.

When a new account is created, an administrator should visit the user profile page under the “People” tab and obtain a link to the account confirmation page. It’s easy to copy that link to the clipboard.

Note: The administrator must not visit the obtained link. The link should be passed along to the user that will confirm the account and possibly set a password. Administrators should have no knowledge of the users’ passwords.

When an existing user needs the password to be reset, the user should ask the administrator for a password reset link. As above, this link can be easily obtained from the user profile page under the “People” tab.

Note: The administrator must not visit the obtained link. The link should be passed along to the user that will confirm the account and possibly set a password. Administrators should have no knowledge of the users’ passwords.

11.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 11.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.
A username or DN containing a forward slash (/) is not supported.

There are additional constraints when LDAP bind credentials are not configured in RStudio Connect:

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 bind credentials when the DN does not contain the username.
Searches will only include users who have previously logged into RStudio Connect.
Groups will be unavailable.

When attempting to troubleshoot a problem relating to LDAP, you can enable more verbose logging by enabling LDAP.Logging in any LDAP configuration section.

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

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

11.6.2 Complete Configuration Examples

IMPORTANT: These examples use a local LDAP server with a fake organization, hierarchy, and credentials. You will need to adjust these samples to your environment. Talk to your LDAP administrator if you need help with your organization’s LDAP hierarchy.

Here are four complete LDAP configuration examples. - Active Directory example with bind credentials (recommended) - OpenLDAP example with bind credentials (recommended) - Active Directory example without bind credentials - OpenLDAP example without bind credentials

11.6.2.1 Activate Directory Example With Bind Credentials

This sample configuration assumes the standard schema for Active Directory.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample AD Configuration With Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
BindDN = "EXAMPLE\\admin"
BindPassword = "XXXXXXXX"
; Users
UserSearchBaseDN = "OU=Users,DC=example,DC=com"
UserObjectClass = "user"
UniqueIdAttribute = "objectGUID"
UsernameAttribute = "sAMAccountName"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"
; Groups
GroupSearchBaseDN = "OU=Users,DC=example,DC=com"
GroupObjectClass = "group"
GroupUniqueIdAttribute = "objectGUID"
GroupNameAttribute = "sAMAccountName"

Note: the Groups portion and the setting that follow it can be omitted if there is no intention to use Active Directory groups.

11.6.2.2 OpenLDAP Example With Bind Credentials

This sample configuration assumed a very simple OpenLDAP structure detailed below.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample OpenLDAP Configuration With Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
BindDN = "cn=admin,dc=example-openldap"
BindPassword = "XXXXXXXX"
; Users
UserSearchBaseDN = "ou=People,dc=example-openldap"
UserObjectClass = "posixAccount"
UniqueIdAttribute = "entryUUID"
UsernameAttribute = "uid"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"
; Groups
GroupSearchBaseDN = "ou=Group,dc=example-openldap"
GroupObjectClass = "posixGroup"
GroupUniqueIdAttribute = "entryUUID"
GroupNameAttribute = "cn"

Note: the Groups portion and the setting that follow it can be omitted if there is no intention to use LDAP groups.

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

dn: uid=management,ou=Groups,dc=example-openldap
objectClass: posixGroup
sn: Doe
memberUid: john
cn: Management
entryUUID: d7682e34-d688-99f0-1037-58dac1afa3d6

11.6.2.3 Active Directory Example Without Bind Credentials

This sample configuration is a modified version of the Active Directory sample above without bind credentials or group support.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample AD Configuration Without Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
; Users
UserSearchBaseDN = "OU=Users,DC=example,DC=com"
UserObjectClass = "user"
UniqueIdAttribute = "objectGUID"
UsernameAttribute = "sAMAccountName"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"

11.6.2.4 OpenLDAP Example Without Bind Credentials

This sample configuration is a modified version of the OpenLDAP sample above without bind credentials or group support.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration Without Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
; Users
UserSearchBaseDN = "ou=People,dc=company,dc=com"
UserObjectClass = "posixAccount"
UniqueIdAttribute = "entryUUID"
UsernameAttribute = "uid"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"

11.6.3 LDAP or AD Configuration Settings

11.6.3.1 `ServerAddress`

LDAP.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 “ldaps”). 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

11.6.3.2 `TLS`

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

Note: This setting implies the use of the legacy “ldaps” protocol (LDAP + SSL) which in general is served on the port 636.

Examples

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

11.6.3.3 `StartTLS`

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

Note: This setting must not be used with the legacy “ldaps” protocol. In general, a connection upgrade to use the TLS encryption can be attempted in the standard LDAP port 389.

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
[LDAP "Sample LDAP Configuration"]
Logging = true

11.6.3.4 `TLSCACertificate`

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.

Examples

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

Note: If either LDAP.TLS or LDAP.StartTLS are enabled, without a certificate the connection will fail unless LDAP.ServerTLSInsecure is enabled.

11.6.3.5 `ServerTLSInsecure`

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

11.6.3.6 `BindDN` and `BindPassword`

LDAP.BindDN and LDAP.BindPassword are credentials used to connect to an LDAP/AD server to authenticate, search for users, and other functionality. While it is recommended to specify these two attributes, it is not required. Without these credentials the use of LDAP is mostly limited to user authentication and LDAP group support cannot be used.
These credentials should have read-only administrator’s rights, if configured.

Note: The BindPassword or BindPasswordFile can be encrypted to avoid credential leakage. See the appendix section A.1.3 for details.

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
; Double slashes (\\) escape the backslash
BindDN = COMPANY\\admin
BindPassword = "adminpassword"

11.6.3.7 `AnonymousBind`

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

11.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)
nsUniqueID (389 Directory Server)

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

The default value of DN is stored in RStudio Connect in plain text. However, any other attribute will be stored encoded as base64 since some LDAP vendors (i.e. Microsoft) send binary values for user identities.

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

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

11.6.3.9 `UserSearchBaseDN`

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

11.6.3.10 `UserObjectClass`

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

11.6.3.11 `UserFilterBase`

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

Either LDAP.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))

11.6.3.12 `UsernameAttribute`

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

Note: The usernames returned by LDAP or Active Directory are not required to be unique. However, this is only supported when the equal usernames are coming from separate LDAP or Active Directory connections in RStudio Connect. When the same username is being returned in a single LDAP connection (for example in an Active Directory global catalog configurarion) then the username must be unique. That may require usernames to use a different LDAP attribute that contains the domain information to distinguish each user.

Examples

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

11.6.3.13 `UserFirstNameAttribute`

LDAP.UserFirstNameAttribute is the LDAP entry attribute that contains the first name of a user. If your LDAP does not provide this information you can leave it empty. If the setting UserLastNameAttribute is also left empty then first and last names will be editable in RStudio Connect according to the setting Authorization.UserInfoEditableBy.

Examples

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

11.6.3.14 `UserLastNameAttribute`

LDAP.UserLastNameAttribute is the LDAP entry attribute that contains the last name of a user. If your LDAP does not provide this information you can leave it empty. If the setting UserFirstNameAttribute is also left empty then first and last names will be editable in RStudio Connect according to the setting Authorization.UserInfoEditableBy.

Examples

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

11.6.3.15 `UserEmailAttribute`

LDAP.UserEmailAttribute is the LDAP entry attribute that contains the email address of a user. If your LDAP does not provide this information you can leave it empty. Email addresses will then be editable in RStudio Connect according to the setting Authorization.UserInfoEditableBy.

Note: Email features will not be available for the user until an email address is entered in the user profile.

Examples

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

11.6.3.16 `PermittedLoginGroup`

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

11.6.3.17 `GroupUniqueIdAttribute`

LDAP.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 11.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.3

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

11.6.3.18 `GroupObjectClass`

LDAP.GroupObjectClass 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 LDAP.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

11.6.3.19 `GroupFilterBase`

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

Either LDAP.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))

11.6.3.20 `GroupNameAttribute`

LDAP.GroupNameAttribute 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

11.6.3.21 `GroupSearchBaseDN`

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

11.7 SAML

RStudio Connect can integrate with the SAML Identity Provider (or IdP) of your company’s choice to perform user authentication and, optionally, user/group membership management. In the SAML world, RStudio Connect fulfills the role of service provider (or SP). Note that user searching in RStudio Connect will search local users only as SAML provides no such user search capability.

RStudio Connect supports SAML 2.0 only.

RStudio Connect will use SAML authentication if the Authentication.Provider setting has a value of saml.

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

Appendix A.16 contains information about each SAML configuration option.

Note: Though it is not typically required, the Server.Address configuration option is required when using SAML as the authentication provider.

SAML support in RStudio Connect has the following constraints:

A user is uniquely identified in Connect by the attribute defined in SAML.UniqueIDAttribute or the same field in the profile specified by SAML.IdPAttributeProfile. This defaults to "NameID" which is a standard identifier for the authenticated Subject which offers a broad compatibility with different SAML Identity Providers. If your IdP is set up to use the transient format for Name IDs, then this value must be specified to something other than NameID.

Note: The value that identifies the user must be immutable during the user’s entire lifetime. Otherwise Connect will not be able to identify the user and will create a new one. For this reason, usernames and email addresses should be avoided as UniqueIDs unless it is the only option, since those can change over time.
A user’s username, first name, last name, and email address may be mapped from any SAML assertion attribute. If a mapping is not configured, the corresponding field will be editable in RStudio Connect, subject to the Authorization.UserInfoEditableBy configuration option.
Changes to fields mapped to SAML assertion attributes for a user (e.g. their name, email address, or username) will not propagate to RStudio Connect until the next time that user logs in.
If configured, groups that the user belongs to may also be mapped from a named SAML assertion attribute. When user groups are mapped, provisioning of those groups in RStudio Connect is also available.
It is highly recommended that RStudio Connect be configured to listen on a port secured with TLS to make sure SAML login assertions are posted to the RStudio Connect server in a secure manner. See Section A.6 for a list of the options available when configuring TLS.
Authentication requests initiated by RStudio Connect are valid for 15 minutes. If a response to an expired request is posted from an Identity Provider for a user, the login will fail and the user will need to initiate a new request.
The number of authentication requests initiated by RStudio Connect is limited to 1000 concurrent attempts after which any other requests will be refused until any responses which correlate with open requests are processed or some of those requests expire.

When attempting to troubleshoot a problem relating to SAML, you can enable more verbose logging by enabling SAML.Logging in the SAML section.

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
Logging = true

11.7.1 Defining a SAML Section

Start a SAML configuration with a SAML section header like the following:

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
...

11.7.2 Identity Provider Configuration

There are two ways to configure the information RStudio Connect needs about your SAML Identity Provider (or IdP), either by the IdP’s metadata or by using specific configuration options.

Note: RStudio Connect requires that the SAML IdP be configured to sign all the messages it sends. As such, the metadata for the IdP must contain a signing certificate. Or, if you are using the specific options, the SAML.IdPSigningCertificate option is required.

11.7.2.1 Using an IdP’s Metadata

To configure an IdP by its metadata file, use the SAML.IdPMetaData option. This may be set to either an HTTPS (or HTTP) URL from which the metadata may be retrieved or to the path to a local file that contains the metadata.

For example,

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
IdPMetaData = https://idp.example.com/saml/metadata

tells RStudio Connect to pull the metadata for the IdP from the given URL, whereas

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
IdPMetaData = /a/local/dir/idp.xml

tells RStudio Connect to read the metadata from the named, locally accessible file.

The retrieved, or read, metadata is cached while RStudio Connect is running. If the metadata expires during that time, the first time a user tries to login after the expiration will cause the metadata to be retrieved or read again. If the metadata is still expired (as would be if reading from a local file), that login will fail. Other login attempts will also fail so long as the metadata is expired. The expiration of metadata is used by some IdPs to allow new signing certificates to be issued so this is generally not a problem for URL-based metadata. If you are using file-based metadata, the error will persist until you update the metadata file. Once new, unexpired metadata is available, logins will succeed again.

11.7.2.2 Providing Specifics Yourself

If there is some reason that an IdP’s metadata cannot be made available to the RStudio Connect server, you can provide the information yourself by using the SAML.IdPEntityID, SAML.IdPSingleSignOnServiceURL, and SAML.IdPSigningCertificate configuration options.

The SAML.IdPEntityID option is used to identify the IdP. Since all identity providers must have a public name, this entity ID, it is used to verify that SAML messages are being received from the correct system.

The SAML.IdPSingleSignOnServiceURL option is used to tell RStudio Connect where to send (via POST or redirect) authentication requests for a user attempting to log in. The IdP system must be listening for this URL for SP-initiated logins. In the case where RStudio Connect is configured for IdP-initiated logins only, this must be the IdP’s user login page.

The SAML.IdPSigningCertificate specifies the public side of the key that the IdP will use to sign the messages it sends to RStudio Connect. It may be the path to a PEM file or the raw, base64 encoded certificate. When not configuring IdP information from metadata, this option must be specified.

If you use these options, you must not specify the SAML.IdPMetaData option, as that will override these. A warning is logged during RStudio Connect startup if this condition exists.

11.7.3 Supporting Encrypted Responses

If you (or your IdP) want the IdP to post encrypted SAML responses to complete login operations, you need to make a security key pair available to both sides. The IdP must be given the public certificate side of the key pair; how this is done varies by IdP. The key must be an RSA key pair. The openssl or ssh-keygen commands are the most common tools to use to generate a new key pair. Refer to the documentation for your tool of choice; the goal is to create two PEM files, one with the private key and one with the public certificate.

Use the SAML.SPEncryptionKey configuration option to provide the private part of the key pair to RStudio Connect. It must be provided if you want encryption support to be enabled. It must be a path to an RSA private key file in PEM format.

Use the SAML.SPEncryptionCertificate to provide the public certificate to RStudio Connect. Do this to include the certificate in the SP metadata that RStudio Connect will produce. Providing this to RStudio Connect is not required for encryption support to work.

11.7.4 SAML Binding

Use the SAML.IdPSingleSignOnPostBinding option to note whether you want RStudio Connect to use POST binding (true) or redirect binding (false, the default) when RStudio Connect is to initiate a single sign-on operation with your IdP. Redirect is the most common choice.

If you use POST binding, RStudio Connect will return a hidden HTML form which will automatically be submitted to the IdP single sign-on page, where either the page will be displayed, or if a user is already logged in, continue through the login process and log the user into Connect.

If the IdP is configured by its metadata, RStudio Connect will verify that the IdP makes an SSO location available using the binding requested here. If the IdP metadata indicates multiple bindings are supported, the SAML.IdPSingleSignOnPostBinding option controls which one will be used.

11.7.5 Name ID Format

When a SAML IdP identifies an authenticated user to a service provider, that user is (typically) identified by what SAML calls a “NameID”. There are four possible formats this name ID may be in. The IdP may support multiple values for this. Use the SAML.NameIDFormat option to tell RStudio Connect which of them your IdP will use. This may be set to transient, persistent, emailAddress or unspecified; the last will be used if this option is not provided. If you specify an IdP attribute profile with SAML.IdPAttributeProfile (see below) the NameID format in the profile will take precedence over this option.

If a NameID format is explicitly defined, either by using a profile or the SAML.NameIDFormat option, it will be included as part of the SAML SP metadata RStudio connect will serve from its /__login__/saml URI. This is true even if the format is set to unspecified. If the SAML.NameIDFormat option is omitted, them the SP metadata will not mention NameIDFormat. See section 11.7.10.1 below for more details about SP metadata.

If the IdP is configured by its metadata and the metadata advertises the formats supported by the IdP, RStudio Connect will verify that the value specified by the SAML.NameIDFormat or from the IdP attribute profile option is supported by the IdP using the following rules:

If the value configured for RStudio Connect is unspecified, any values from the IdP will be accepted.
If the value configured for RStudio Connect is anything else, it will be accepted if it is present in the IdP list of formats. If the IdP list contains unspecified and the Connect format is not in that list, then it will be accepted but a warning will be logged noting that the configuration may need to be adjusted. In this situation, this may or may not work, depending on your specific IdP.

11.7.6 Single Sign-On Initiation

The SAML specification allows for a single sign-on flow to be initiated by either the IdP or SP. Use the SAML.SSOInitiated option to control this. There are three possible values.

IdP – This indicates that single sign-on may be initiated at the IdP only. In this mode, an end user must visit the sign-on page of their IdP and select RStudio Connect as the service provider to use.

Note: In this mode, you will not be able to use the IdP’s metadata to configure the IdP’s information; you will need to use the separate configuration options. When the IdP is used to initiate authentication, this causes a problem when publishing from the RStudio IDE. Since the IDE can only know about RStudio Connect, RStudio Connect must respond by returning a “blind” redirect to to the IdP’s sign-on page. This must be configured in the SAML.IdPSingleSignOnServiceURL configuration option.
IdPAndSP – This indicates that single sign-on may be initiated by either the IdP or by RStudio Connect. In this case, note that the RStudio IDE will always use the service provider initiated flow. This is the default.
SP – This indicates that single sign-on may be initiated only by RStudio Connect. In this mode, an IdP-initiated login will fail, since there would be no matching authentication request that RStudio Connect has sent out.

11.7.7 User Attribute Mapping

When a user is authenticated by an IdP, certain data about the user may be included in the authentication response. These are most commonly called attributes, assertion attributes or claims. So that RStudio Connect may manage its user information correctly, it needs to understand these. Since this mapping includes the Unique ID, the appropriate NameIDFormat for that ID is also included in the profile.

RStudio Connect can automatically assign users to groups when SAML authentication assertion includes group membership information. This is expected to be in the form of a single attribute containing a list of all groups, by name, that the user belongs to. In the rare event that an IdP cannot list groups as a list of distinct values, you can use the SAML.GroupsSeparator configuration option to specify a separator string that will be used to split a single value into a list. For example, if the groups attribute contains a value of the form, group_1|group_2, set the SAML.GroupsSeparator configuration option to | and RStudio Connect will break the one value into the represented list of group names.

If the groups attribute is mapped, RStudio Connect will adjust the group memberships of the user logging in to match the list provided in the assertion, adding the user to named groups when necessary and removing them from groups that are no longer listed.

If group membership information is not mapped from the IdP, they are still supported when using SAML authentication. In this case, they can be managed manually in the Connect dashboard or via the Connect Server API.

Note: When group membership is not sourced from the IdP, groups are local to RStudio Connect and have no relation to any external groups.

If you do not want groups at all, set the Authorization.UserGroups configuration option to false.

Note: SAML attributes in the authentication response are case sensitive.

There are two ways to tell RStudio Connect about how this data is mapped.

11.7.7.1 Using Attribute Profiles

There are times when RStudio will know ahead of time what the field mapping for a particular IdP should be. When that is the case, an appropriate attribute profile will be available in RStudio Connect’s database.

Use the SAML.IdPAttributeProfile configuration option to specify the profile RStudio Connect should use. By default, this enables the mapping of group membership information. If you want to use a profile but do not want to use groups, set the SAML.IdPAttributeProfileGroups configuration option to false. If you specify a profile, you cannot specify any of the SAML.UniqueIDAttribute, SAML.NameIDFormat, SAML.UsernameAttribute, SAML.FirstNameAttribute, SAML.LastNameAttribute, SAML.EmailAttribute or SAML.GroupsAttribute options, as they will be overridden by the profile. A warning is logged during RStudio Connect startup if this condition exists.

Below is a description of each of the known profiles and the assertion names each expects shown as their configuration equivalents. See section 11.7.7.2 below for details about the individual configuration options.

11.7.7.1.1 The `default` Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
UniqueIDAttribute = NameID
NameIDFormat = persistent
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = Email
GroupsAttribute = Groups

11.7.7.1.2 The `okta` Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
UniqueIDAttribute = NameID
NameIDFormat = persistent
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = Email
GroupsAttribute = Groups

11.7.7.1.3 The `onelogin` Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
UniqueIDAttribute = NameID
NameIdFormat = emailAddress
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = NameID

11.7.7.1.4 The `azure` Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
UniqueIdAttribute = NameID
NameIDFormat = persistent
UsernameAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
FirstNameAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
LastNameAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
EmailAttribute = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailAddress
GroupsAttribute = http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

11.7.7.2 Specifying Attributes Yourself

Use the SAML.UsernameAttribute, SAML.FirstNameAttribute, SAML.LastNameAttribute and SAML.EmailAttribute configuration options to set the names of the attributes to look for in obtaining the related values. For each of these that are not specified (when not using an attribute profile), RStudio Connect will assume management of the fields, making them editable in the Connect dashboard. If you wish to make use of group information, use the SAML.GroupsAttribute option to set the name of the attribute to look for. This allows for users to automatically be added to groups that are manually created within Connect.

You must include either the SAML.UsernameAttribute or the SAML.EmailAttribute option (or both) in your configuration. If you do not configure the username attribute, RStudio Connect will create a new unique username for a user the first time that user logs in. The username will be derived from the user’s email address, without the domain, adding a numeric suffix as needed for uniqueness. These usernames are editable.

Note: The usernames returned by the SAML provider are not required to be unique when SAML.UsernameAttribute is configured.

The ways SAML.UniqueIDAttribute and SAML.NameIDFormat are configured to identify users in RStudio Connect are detailed above.

Note: The value obtained from SAML.UniqueIDAttribute must match exactly the field unique_id used for creating new users via the Connect Server API. Once the user is created, the RStudio Connect identity (guid) should be used for subsequent API operations with that user.

11.7.7.3 Automatic Group Provisioning

In addition to delegating group membership management to the IdP, RStudio Connect can also delegate the management of groups themselves to the IdP. By using SAML.GroupsAutoProvision RStudio Connect will automatically create and optionally remove groups based on the list of group names received from the IdP.

With this option enabled groups are provisioned in RStudio Connect when the first member is added and remain there indefinitely, even after the last member has been removed, so that any access to content is preserved for a future member of those groups.

Note: RStudio Connect can be configured to automatically decommission (remove) groups without members with the additional setting SAML.GroupsAutoRemoval. It also removes the group from all content it has been previously associated with.

In this mode, it is assumed that all group management will be done externally to RStudio Connect and therefore the user interface for group management will be hidden in the Connect dashboard.

11.7.7.4 Switching Between Manual and Automatic Group Provisioning

Groups created by automatic provisioning do not have owners while any groups created manually or via the Connect Server API are always associated with a user.

RStudio Connect will issue a warning on startup if the ownership of the existing groups does not match the provider configuration.

In these situations, either the group needs to be removed or group ownership needs to be adjusted. This can be done with the usermanager CLI tool with the alter command using the --new-owner or --drop-owner switches.

Note: Additional to group ownership, groups created manually or via the Connect Server API may not match the names of the groups sent by the IdP and therefore those cannot be removed if both auto provisioning and auto removal are enabled. The Connect Server API can also be used to remove these extra groups.

11.7.8 Metadata Configuration Example

Here is a complete SAML configuration as an example. It tells RStudio Connect to communicate to an IdP by retrieving its metadata from the given URL. Single sign-ons can be initiated by either party. The IdP will use the persistent NameID format. The user fields will be mapped from the assertion attributes as defined in the default profile. In that profile, the Unique ID will be the name ID from the IdP.

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
IdPMetaData = https://idp.example.com/saml2/metadata
IdPAttributeProfile = default

You can also configure the use of metadata with individual user attribute names. This example is equivalent to the one above.

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
IdPMetaData = https://idp.example.com/saml2/metadata
NameIDFormat = persistent
UsernameAttribute = "Username"
FirstnameAttribute = "FirstName"        
LastnameAttribute = "LastName"      
EmailAttribute = "Email"

11.7.9 Individual Settings Configuration Example

Here is a complete SAML configuration as an example but now using individual settings when a metadata is not available or cannot be used. Single sign-ons can be initiated by the IdP only, Connect will redirect to a login page on the IdP if the authentication is attempted first in Connect (which will happen with the RStudio IDE), the signing certificate (shortened for brevity) is a raw base64 value, while the encryption key and certificate are paths to PEM files and because transient is being used the UniqueIDAttribute is something other than the NameID.

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
SSOInitiated = IdP
IdPEntityID = https://idp.example.com/saml2/metadata
IdPSingleSignOnServiceURL = https://idp.example.com/login
IdPSigningCertificate = MIADHIUfdhfkhkdshkf454sdfe5e64fF45FF5456456d4d65 ... fd378==
SPEncryptionKey = /path/to/rsa.key
SPEncryptionCertificate = /path/to/pem.cer
NameIDFormat = transient
UniqueIDAttribute = "GUID"
UsernameAttribute = "Username"
FirstnameAttribute = "FirstName"
LastnameAttribute = "LastName"
EmailAttribute = "Email"
GroupsAttribute = "Groups"

11.7.10 Service Provider Configuration for the IdP

Though the number of available IdPs is large and each one has its own configuration process, there are some common things to know.

Almost all IdPs will require you to define and configure the service providers that they should interact with, including RStudio Connect. They may use different terms, but there are three pieces of information you will need to provide to the IdP.

The first two items below can sometimes be configured in the IdP by way of providing the metadata XML document for the SP. This is generally preferable when available. See the following section for more details.

Service Provider EntityID – This is a string that uniquely identifies RStudio Connect as a service provider to the IdP. This might be labeled in other ways such as, Entity ID, Name, Destination, Audience, Audience Restriction, etc. This is typically a URL to the metadata provided by the SP but doesn’t need to be.

You should use a value of https://<hostname>[:port]/__login__/saml for RStudio Connect, replacing hostname and port as appropriate. These should match what is specified in the Server.Address configuration option.

Note: It is important that when using the above URL as the entity ID it must not contain a trailing / character; this will prevent logins from working as the audience field provided by the IdP will not match the entity ID that RStudio Connect will use.

It is not required that the IdP be able to access this if it’s a URL.
Assertion Consumption Service – This is a URL in the service provider where the IdP will post authentication responses. This is important when initiating an authentication at the IdP. This may also be labeled as Single sign on URL, SSO URL, ACS URL, etc.

You should use a value of https://<hostname>[:port]/__login__/saml/acs for RStudio Connect, replacing hostname and port as appropriate. These should match what is specified in the Server.Address configuration option.

Note: Make sure the ACS URL you provide does not contain a trailing slash. Having one will prevent logins from working.
Attribute Mapping – This is the mapping of fields known within the IdP to the attribute names that will be used for them in authentication responses. They are usually specified in name/value pairs though they may include a name format specification.

Each name is the string by which its value will be known in authentication responses and must match the values specified in the SAML.UsernameAttribute, SAML.FirstNameAttribute, SAML.LastNameAttribute and SAML.EmailAttribute configuration options. The matching of these names is case sensitive.

11.7.10.1 RStudio Connect SAML MetaData

Some IdPs can configure basic information about a service provider from its metadata file. RStudio Connect will serve its SAML metadata from the https://<hostname>[:port]/__login__/saml endpoint (the same as RStudio Connect’s entity ID). If the IdP accepts a URL for the SP’s metadata (and the IdP has the means to reach RStudio Connect), you should use the entity ID as the URL. If the IdP accepts an upload of the SP’s metadata file, you can use the curl command to get the SAML metadata from RStudio Connect as follows:

curl https://localhost:3443/__login__/saml --output metadata.xml

The above assumes you are executing curl from the machine where RStudio Connect is running and will write the metadata XML document to a file called metadata.xml in the current directory. The same command, or even a browser, may be used from anywhere that RStudio Connect is accessible.

11.8 OAuth2 (Google Apps with OpenID Connect)

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

When attempting to troubleshoot a problem relating to OAuth2, you can enable more verbose logging with OAuth2.Logging:

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
Logging = true

11.8.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”.
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”.
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).
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 OAuth2.ClientId and either OAuth2.ClientSecret or OAuth2.ClientSecretFile configured, you can use your Google Apps account to sign into RStudio Connect!

Note: The ClientSecret or ClientSecretFile can be encrypted to avoid leakage of the credential. See the appendix section A.1.3 for details.

11.8.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.AllowedDomain setting specifies the set of domains that are allowed to access your RStudio Connect server. Multiple domains should be entered one per line.

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
AllowedDomain = company.com
AllowedDomain = subsidiary.com

You may also restrict access by email address if using domain alone is insufficient. The OAuth2.AllowedEmail setting specifies the set of email addresses that are allowed to access your RStudio Connect server. Multiple addresses should be entered one per line.

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
AllowedEmail = jdoe@company.com
AllowedEmail = asmith@subsidiary.com

It is important to understand how the OAuth2.AllowedDomain and OAuth2.AllowedEmail properties interact.

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

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

When both OAuth2.AllowedDomain and OAuth2.AllowedEmail are specified, email addresses given in OAuth2.AllowedEmail are permitted access in addition to email addresses with a domain listed in OAuth2.AllowedDomain.

11.8.3 Usernames

Google OAuth2 has no notion of usernames but certain features in RStudio Connect require a username. On the user’s first login or when the user is associated with some content, we derive the initial username from the user’s email address without the domain. The user may be able to modify it after the first login if allowed. An administrator is always able to modify OAuth2 usernames.

The process of generating an initial username is limited to what is considered a valid username in RStudio Connect. For example, certain characters such as dashes (-) are replaced with underscores (_), shorter names are also padded with underscores. Resulting usernames longer than 64 characters are truncated as necessary and prohibited or duplicate usernames get an incremental suffix.

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

11.8.5 Groups

Groups are supported when using OAuth2 authentication. They can be managed manually in the Dashboard or via the Connect Server API.

Note: These groups are local to RStudio Connect and have no relation to any organization groups present in Google Apps, for example.

11.9 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 14.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 14.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.

When attempting to troubleshoot a problem relating to PAM, you can enable more verbose logging with PAM.Logging:

; /etc/rstudio-connect/rstudio-connect.gcfg
[PAM]
Logging = true

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

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

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

11.9.4 Groups

Groups are supported when using PAM authentication. They can be managed manually in the Dashboard or via the Connect Server API.

Note: These groups are local to RStudio Connect and have no relation with Unix/Linux groups present in the host machine where PAM is configured.

11.10 Proxied Authentication

RStudio Connect supports proxied authentication. This allows an external system to intercept requests and handle the authentication of users visiting the RStudio Connect dashboard or applications Connect is hosting.

11.10.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 custom HTTP headers added before the request is proxied through to RStudio Connect. The HTTP headers will contain the username and other identifying information of that visitor. RStudio Connect will take the values from the HTTP headers and treat the traffic as the user specified in the headers.

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 network access to the RStudio Connect server is properly limited by a firewall or other network restriction. All access to RStudio Connect must be proxied through your authentication server.

Important Note

The HTTP header identifying the user 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.

11.10.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 proxied 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

11.10.3 Using the RStudio Connect Server API

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.

11.10.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.4.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

RStudio Connect can also be configured to receive more complete user profile information from the proxy via additional headers.

; /etc/rstudio-connect/rstudio-connect.gcfg
[ProxyAuth]
UsernameHeader = X-Auth-Username
FirstNameHeader = X-Auth-First-Name
LastNameHeader = X-Auth-Last-Name
EmailHeader = X-Auth-Email

A user’s username, first name, last name, and email address may be mapped from the headers as in the example above. If a mapping is not configured, the corresponding field will be editable in RStudio Connect, subject to the Authorization.UserInfoEditableBy configuration option.

Note: The fields configured to be sent by the proxy are not editable via the RStudio Connect dashboard or Connect Server API. Any updated values sent by the proxy will be reflected in the user’s profile the next time that user logs in. A non-editable field (one configured to be sent in the proxy headers) can be forcefully updated before a login via the usermanager CLI tool. See B.3.

Additionally, a user role in RStudio Connect can be informed via a proxy header. Use the setting ProxyAuth.RoleHeader to inform which header will contain the role.

Note: The role header accepts the values viewer, publisher or administrator. Invalid values are defaulted to value of Authorization.DefaultUserRole and an error is reported in the logs.

11.10.4.1 Supporting Changes to the Username

By default, the username is the only means of user identity required by RStudio Connect, and every new username gets a new account in RStudio Connect. If you wish to be able to update usernames over time while maintaining a single account for each user, a different form of unique user identity must be provided via the proxy headers.

The setting ProxyAuth.UniqueIdHeader determines which header holds the user identity. It’s important that the user identity sent over this header by the proxy be:

Unique: It is extremely important that different users do not have the same identity.
Persistent: Ideally this identity must not be attached to the username, email or names, since those may change over time. Values based on UUID/GUID are a great options if your authentication system provides them.

Note: When configured this way, usernames provided by the proxy are not required to be unique.

IMPORTANT: Existing customers willing to enable the ProxyAuth.UniqueIdHeader MUST first update all users to the new identity before configuring the setting. The usermanager CLI tool can help in this migration. See B.3

Note: Configuring ProxyAuth.UniqueIdHeader also enables the RStudio Connect Server API to accept the field unique_id for creating new users. This value must match the value sent by the proxy via headers. Internally in Connect, the UniqueID is stored encoded as a base64 value. Once the user is created, the RStudio Connect identity (guid) should be used for subsequent API operations with that user.

When the ProxyAuth.UniqueIdHeader option is configured, you must include either the ProxyAuth.UsernameHeader or the ProxyAuth.EmailHeader option (or both) in your configuration. If you do not configure the username attribute, RStudio Connect will create a new unique username for a user the first time that user logs in. The username will be derived from the user’s email address, without the domain, adding a numeric suffix as needed for uniqueness if necessary. These usernames are editable.

11.10.4.2 Supporting Groups

The setting ProxyAuth.GroupsHeader defines the name of the header containing the names of the groups the authenticating user is member of.

The list of group names sent by the proxy is compared with the memberships the user currently has in RStudio Connect and then any missing memberships are added to existing groups and any memberships that no longer apply are removed.

By default it is expected that multiple groups names will come as separate occurrences of the same header, for example:

; /etc/rstudio-connect/rstudio-connect.gcfg
[ProxyAuth]
GroupsHeader = X-Auth-Groups

HTTP Request:

X-Auth-Groups: Engineering
X-Auth-Groups: Managers
...

However, it is also possible to send group names on a single header. In this case, the group names in the header value must be sent as a separated list. Use the setting ProxyAuth.GroupsHeaderSeparator to enable this behavior and set which character should be used to split the group names.

For example:

; /etc/rstudio-connect/rstudio-connect.gcfg
[ProxyAuth]
GroupsHeader = X-Auth-Groups
GroupsHeaderSeparator = "|"

HTTP Request:

X-Auth-Groups: Engineering|Managers|...

Note: Certain characters cannot be used as separators since they are prohibited in HTTP headers. The RFC 7230 define those.

11.10.4.3 Automatic Group Provisioning

In addition to delegating group membership management to the authentication engine behind the proxy, RStudio Connect can also delegate the management of groups themselves to the proxy. By using ProxyAuth.GroupsAutoProvision RStudio Connect will automatically create and optionally remove groups based on the list of group names received from the proxy.

Note: RStudio Connect can be configured to automatically decommission (remove) groups without members with the additional setting ProxyAuth.GroupsAutoRemoval. It also removes the group from all content it has been previously associated with.

In this mode, it is assumed that all group management will be done externally to RStudio Connect and therefore the user interface for group management will be hidden in the RStudio Connect dashboard.

11.10.4.4 Switching Between Manual and Automatic Group Provisioning

Groups created by automatic provisioning do not have owners while any groups created manually or via the Connect Server API are always associated with a user.

RStudio Connect will issue a warning on startup if the ownership of the existing groups does not match the provider configuration.

Note: Additional to group ownership, groups created manually or via the Connect Server API may not match the names of the groups sent by the proxy and therefore those cannot be removed if both auto provisioning and auto removal are enabled. The Connect Server API can also be used to remove these extra groups.

11.10.5 Troubleshooting Proxied Authentication

When attempting to troubleshoot a problem relating to proxied authentication, you can enable more verbose logging with ProxyAuth.Logging:

; /etc/rstudio-connect/rstudio-connect.gcfg
[ProxyAuth]
Logging = true

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 proxied authentication attempt” appears in the server logs, users cannot log in
1. Ensure that the proxy is configured to delete the configured username, names, email and unique identity headers 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')

See 11.10.2

Attempts to use the Connect Server API 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 Authentication header with a Key value.
2. Ensure that the proxy is not blocking other headers that may be required by hosted APIs (i.e. Plumber, TensorFlow, etc.)

See 11.10.3

11.10.6 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. A similar logic is applied to remaining examples that send additional user information.

IMPORTANT: These examples are intended to aid with an initial configuration of RStudio Connect behind an authenticating proxy. They are not recommended for production environments and have severe functional limitations (i.e. ' and ; are not accepted in values because the examples use plain text cookies) and offer no security at all. Customers are urged to adhere to the best security practices and recommended settings for their proxy.

All examples below are based on how to run a proxy in front of RStudio Connect. See 7.

11.10.6.1 Basic configuration example

The bare minimum to allow a user coming from an authentication proxy to enter RStudio Connect. It assumes default values for the existing settings for proxied authentication. See 11.10.4.

These examples send traffic through the proxy if the verified-user cookie is present. The examples also allow traffic for deployments from the RStudio IDE or API use if the respective headers are present. See 11.10.3 and 11.10.2.

Nginx:

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:

RewriteEngine 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>

  # store variable values with dummy rewrite rules
  RewriteRule . - [E=req_scheme:%{REQUEST_SCHEME}]
  RewriteRule . - [E=http_host:%{HTTP_HOST}]
  RewriteRule . - [E=req_uri:%{REQUEST_URI}]
  # set header with variables
  RequestHeader set X-RSC-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"

  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteCond %{HTTP:Connection} upgrade [NC]
  RewriteRule ^/(.*) "ws://rstudio-connect-host:3939/$1" [P,L]

  <If "-n env('AuthUsername')">
    RequestHeader set X-Auth-Username "%{AuthUsername}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Username
  </Else>

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

11.10.6.2 Configuration example with user profile support

These configurations extend the basic examples and add support for headers carrying user profile information, such as names and email. The names for the different headers must be also present in your RStudio Connect configuration. See 11.10.4.

Nginx:

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

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

map $http_cookie $auth_firstname {
  default "";
  "~*proxyauth-as-first=(?<first>[^;]+)" "$first";
}

map $http_cookie $auth_lastname {
  default "";
  "~*proxyauth-as-last=(?<last>[^;]+)" "$last";
}

map $http_cookie $auth_email {
  default "";
  "~*proxyauth-as-email=(?<email>[^;]+)" "$email";
}

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;
    proxy_set_header           X-Auth-Firstname $auth_firstname;
    proxy_set_header           X-Auth-Lastname $auth_lastname;
    proxy_set_header           X-Auth-Email $auth_email;    
  }
}

Apache:

RewriteEngine on

<VirtualHost *:80>
  SetEnvIf Cookie "verified-user=([^;]+)" AuthUsername=$1
  SetEnvIf Cookie "proxyauth-as-first=([^;]+)" AuthFirstName=$1
  SetEnvIf Cookie "proxyauth-as-last=([^;]+)" AuthLastName=$1
  SetEnvIf Cookie "proxyauth-as-email=([^;]+)" AuthEmail=$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>

  <If "-n env('AuthUsername')">
    RequestHeader set X-Auth-Username "%{AuthUsername}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Username
  </Else>
  <If "-n env('AuthFirstName')">
    RequestHeader set X-Auth-Firstname "%{AuthFirstName}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Firstname
  </Else>
  <If "-n env('AuthLastName')">
    RequestHeader set X-Auth-Lastname "%{AuthLastName}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Lastname
  </Else>
  <If "-n env('AuthEmail')">
    RequestHeader set X-Auth-Email "%{AuthEmail}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Email
  </Else>
  
  # store variable values with dummy rewrite rules
  RewriteRule . - [E=req_scheme:%{REQUEST_SCHEME}]
  RewriteRule . - [E=http_host:%{HTTP_HOST}]
  RewriteRule . - [E=req_uri:%{REQUEST_URI}]
  # set header with variables
  RequestHeader set X-RSC-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"

  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteCond %{HTTP:Connection} upgrade [NC]
  RewriteRule /rsconnect/(.*) "ws://rstudio-connect-host:3939/$1" [P,L]

  RewriteRule ^/rsconnect$ /rsconnect/ [R]

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

11.10.6.3 Configuration example with user profile and unique identity support

In these examples, username is considered part of the user profile. An additional header is used to communicate user identity. See 11.10.4.

Nginx:

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

map $http_cookie $auth_uniqueid {
  default "";
  "~*proxyauth-as-id=(?<uniqueid>[^;]+)" "$uniqueid";
}

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

map $http_cookie $auth_firstname {
  default "";
  "~*proxyauth-as-first=(?<first>[^;]+)" "$first";
}

map $http_cookie $auth_lastname {
  default "";
  "~*proxyauth-as-last=(?<last>[^;]+)" "$last";
}

map $http_cookie $auth_email {
  default "";
  "~*proxyauth-as-email=(?<email>[^;]+)" "$email";
}

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

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

map "$auth_uniqueid:$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-Uniqueid $auth_uniqueid;
    proxy_set_header           X-Auth-Username $auth_username;
    proxy_set_header           X-Auth-Firstname $auth_firstname;
    proxy_set_header           X-Auth-Lastname $auth_lastname;
    proxy_set_header           X-Auth-Email $auth_email;    
  }
}

Apache:

RewriteEngine on

<VirtualHost *:80>
  SetEnvIf Cookie "verified-user=([^;]+)" AuthUniqueId=$1
  SetEnvIf Cookie "proxyauth-as-user=([^;]+)" AuthUsername=$1
  SetEnvIf Cookie "proxyauth-as-first=([^;]+)" AuthFirstName=$1
  SetEnvIf Cookie "proxyauth-as-last=([^;]+)" AuthLastName=$1
  SetEnvIf Cookie "proxyauth-as-email=([^;]+)" AuthEmail=$1

  <If "%{REQUEST_URI} !~ m#^/auth# && -z env('AuthUniqueId') && -z %{HTTP:X-Auth-Token} && %{HTTP:Authorization} !~ /Key .+/">
    Redirect 307 "%{REQUEST_SCHEME}://%{HTTP_HOST}/auth/login?url=%{REQUEST_URI}"
  </If>

  <If "-n env('AuthUniqueId')">
    RequestHeader set X-Auth-Uniqueid "%{AuthUniqueId}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Uniqueid
  </Else>
  <If "-n env('AuthUsername')">
    RequestHeader set X-Auth-Username "%{AuthUsername}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Username
  </Else>
  <If "-n env('AuthFirstName')">
    RequestHeader set X-Auth-Firstname "%{AuthFirstName}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Firstname
  </Else>
  <If "-n env('AuthLastName')">
    RequestHeader set X-Auth-Lastname "%{AuthLastName}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Lastname
  </Else>
  <If "-n env('AuthEmail')">
    RequestHeader set X-Auth-Email "%{AuthEmail}e"
  </If>
  <Else>
    RequestHeader unset X-Auth-Email
  </Else>

  # store variable values with dummy rewrite rules
  RewriteRule . - [E=req_scheme:%{REQUEST_SCHEME}]
  RewriteRule . - [E=http_host:%{HTTP_HOST}]
  RewriteRule . - [E=req_uri:%{REQUEST_URI}]
  # set header with variables
  RequestHeader set X-RSC-Request "%{req_scheme}e://%{http_host}e%{req_uri}e"

  RewriteCond %{HTTP:Upgrade} websocket [NC]
  RewriteCond %{HTTP:Connection} upgrade [NC]
  RewriteRule /rsconnect/(.*) "ws://rstudio-connect-host:3939/$1" [P,L]

  RewriteRule ^/rsconnect$ /rsconnect/ [R]

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

11 Authentication

11.1 Changing Authentication Provider

11.1.1 Uniquely Identifying Users

11.1.2 Updating Groups

11.1.3 Unsupported Authentication Changes

11.2 Session Management

11.3 Username requirements

11.4 User Attribute Editability

11.4.1 Password (Built-in) Authentication

11.4.2 OAuth2 (Google Apps with OpenID Connect)

11.4.3 LDAP or Active Directory

11.4.4 SAML

11.4.5 Proxied Authentication

11.4.6 PAM

11.5 Password (Built-in) Authentication

11.5.1 Groups

11.5.2 Limitations to Remember

11.5.3 Security Considerations

11.5.3.1 Acceptable Passwords

11.5.3.2 Exceptions

11.5.4 Support for Administrators

11.5.5 Without Email Sending

11.6 LDAP and Active Directory

11.6.1 Defining an LDAP or AD section

11.6.2 Complete Configuration Examples

11.6.2.1 Activate Directory Example With Bind Credentials

11.6.2.2 OpenLDAP Example With Bind Credentials

11.6.2.3 Active Directory Example Without Bind Credentials

11.6.2.4 OpenLDAP Example Without Bind Credentials

11.6.3 LDAP or AD Configuration Settings

11.6.3.1 ServerAddress

11.6.3.2 TLS

11.6.3.3 StartTLS

11.6.3.4 TLSCACertificate

11.6.3.5 ServerTLSInsecure

11.6.3.6 BindDN and BindPassword

11.6.3.7 AnonymousBind

11.6.3.8 UniqueIdAttribute

11.6.3.9 UserSearchBaseDN

11.6.3.10 UserObjectClass

11.6.3.11 UserFilterBase

11.6.3.12 UsernameAttribute

11.6.3.13 UserFirstNameAttribute

11.6.3.14 UserLastNameAttribute

11.6.3.15 UserEmailAttribute

11.6.3.16 PermittedLoginGroup

11.6.3.17 GroupUniqueIdAttribute

11.6.3.18 GroupObjectClass

11.6.3.19 GroupFilterBase

11.6.3.20 GroupNameAttribute

11.6.3.21 GroupSearchBaseDN

11.7 SAML

11.7.1 Defining a SAML Section

11.7.2 Identity Provider Configuration

11.7.2.1 Using an IdP’s Metadata

11.7.2.2 Providing Specifics Yourself

11.7.3 Supporting Encrypted Responses

11.7.4 SAML Binding

11.7.5 Name ID Format

11.7.6 Single Sign-On Initiation

11.7.7 User Attribute Mapping

11.7.7.1 Using Attribute Profiles

11.7.7.1.1 The default Profile

11.7.7.1.2 The okta Profile

11.7.7.1.3 The onelogin Profile

11.7.7.1.4 The azure Profile

11.7.7.2 Specifying Attributes Yourself

11.7.7.3 Automatic Group Provisioning

11.7.7.4 Switching Between Manual and Automatic Group Provisioning

11.7.8 Metadata Configuration Example

11.7.9 Individual Settings Configuration Example

11.7.10 Service Provider Configuration for the IdP

11.7.10.1 RStudio Connect SAML MetaData

11.8 OAuth2 (Google Apps with OpenID Connect)

11.8.1 Obtaining a Client ID and Client Secret

11.8.2 Restricting Access

11.8.3 Usernames

11.8.4 Searches

11.8.5 Groups

11.9 PAM

11.6.3.1 `ServerAddress`

11.6.3.2 `TLS`

11.6.3.3 `StartTLS`

11.6.3.4 `TLSCACertificate`

11.6.3.5 `ServerTLSInsecure`

11.6.3.6 `BindDN` and `BindPassword`

11.6.3.7 `AnonymousBind`

11.6.3.8 `UniqueIdAttribute`

11.6.3.9 `UserSearchBaseDN`

11.6.3.10 `UserObjectClass`

11.6.3.11 `UserFilterBase`

11.6.3.12 `UsernameAttribute`

11.6.3.13 `UserFirstNameAttribute`

11.6.3.14 `UserLastNameAttribute`

11.6.3.15 `UserEmailAttribute`

11.6.3.16 `PermittedLoginGroup`

11.6.3.17 `GroupUniqueIdAttribute`

11.6.3.18 `GroupObjectClass`

11.6.3.19 `GroupFilterBase`

11.6.3.20 `GroupNameAttribute`

11.6.3.21 `GroupSearchBaseDN`

11.7.7.1.1 The `default` Profile

11.7.7.1.2 The `okta` Profile

11.7.7.1.3 The `onelogin` Profile

11.7.7.1.4 The `azure` Profile