Skip to content

Auth Provider Migration

Changing Authentication Provider (Migration)#

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:

  1. Stop RStudio Connect.

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

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

  4. 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>
  5. Reconfigure RStudio Connect to use the new authentication provider.

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


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.


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.


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:

  1. Stop RStudio Connect.

  2. Reconfigure RStudio Connect to use the new authentication provider.

  3. Restart RStudio Connect.

  4. If necessary modify the existing user's username to avoid duplicates.

  5. Either create the new user record via the RStudio Connect Server API or require the user to log in.

  6. Stop RStudio Connect.

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

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

  9. 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
  10. 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.


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.


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.