Authentication¶

RStudio Connect supports a variety of user authentication options. Without customization, a locally-backed password scheme is used. The Password Authentication section describes this built-in authentication option. This scheme is the only supported scheme that allows passwords to be changed from within RStudio Connect.

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

External authentication is available through the following integrations:

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

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 the Purging RStudio Connect section for instructions.

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 (Google) 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, OAuth2 (other than Google) 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 the CLI appendix for more information on using the usermanager CLI to manage users.

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 the User Management CLI appendix.

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 the User Management CLI appendix for more details.

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.

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.

Username Requirements¶

When using the built-in Password authentication or PAM usernames are always required and must be unique. PAM usernames are case-sensitive.

When using Google (OAuth2) usernames are not available. Because RStudio Connect requires one for certain operations, a unique username is generated based on the user's email address on first login. These generated usernames are editable in RStudio Connect.

These usernames must adhere to the following convention:

be 3-64 characters in length,
start with a letter, and
contain only alphanumeric characters, underscores, and periods.

In other scenarios, RStudio Connect uses relaxed username requirements. Usernames are not verified for uniqueness. In all cases, the following values are prohibited:

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

Note: The uniqueness of the username is not enforced 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). These usernames are managed by the authentication provider so are not editable in RStudio Connect.

By default, the rules above apply to LDAP, SAML, OpenID Connect (OAuth2). Google (OAuth2) and Proxied authentication can also be configured to allow non-unique usernames controlled by the authentication provider.

On the other hand, OpenID Connect (OAuth2), SAML and Proxied authentication can be configured to not require usernames. In this case, similar to Google (OAuth2), an editable unique username will be generated based on the user's email address. The email becomes a required field for login 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.

Note: The exception for the constraint above is OpenID Connect (OAuth2), which for increased compatibility, requires an additional configuration for this fail-without-username behavior. Instead, OpenID allows authentication without a username claim, resorting to a non-editable username derived from the email.

See more details about usernames for each provider in the User Provisioning section.

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.

Password resets are only handled by RStudio Connect when using the built-in Password Authentication provider. In all other cases, password resets should be performed according to your organization's policies using the authentication product you have integrated.

User Role Editability¶

User roles are only editable in RStudio Connect if Automatic User Role Mapping is not configured, and the authentication provider is not configured to send roles in as part of the user profile.

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.

OAuth2 (OpenID Connect)¶

For OAuth2 (OpenID), first name, last name, and email address are provided by the provider. Therefore, they are not editable by any user by default. If you need to change/update this information, update your OpenID provider and the changes will be synced into RStudio Connect on the next user login.

Note: Forcing the claims for first name, last name or email to blank values in the RStudio Connect configuration will make these fields editable and they will no longer be updated every login.

The behavior around username is dependent on your OpenID vendor. For Google, 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 the User Provisioning section.

For other OpenID Connect vendors, if a claim for the username is present it will be used. Otherwise, like Google a username will be derived from the email.

Note: It is recommended that for OpenID Connect (not Google) the setting OAuth2.RequireUsernameClaim be enabled to enforce usernames and fail to login if one is not present.

The setting Authorization.UserInfoEditableBy controls whether or not your users will be permitted to manage their user profile fields such as 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.

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 the User Provisioning section.

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 LDAP and Active Directory section has more information on how to avoid such issues by using vendor-specific values to identify users.

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

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 the User Provisioning section.

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.

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.

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 the User Provisioning section.

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 the User Provisoning section.

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.