Skip to content

Migrating Authentication Providers#

RStudio Workbench, formerly RStudio Server Pro1 can be configured to authenticate using local Linux accounts, LDAP/Active Directory, SAML, or OpenID Connect (OIDC).

Each user on RStudio Workbench requires a Linux account (username and UID) - and home directory. You may need to change only one, two, or all three of these attributes to migrate authentication.

Authentication Migrations for RStudio Workbench

Migration from local Linux accounts to LDAP/AD#

If you are migrating to LDAP/AD from local Linux accounts, users are automatically created and they authenticate into RStudio Workbench with their LDAP/AD credentials.

The steps are as follows:

  1. Stop RStudio Workbench.
  2. Configure LDAP/AD authentication with RStudio Workbench.
  3. Move all files from old home directories to new ones.
  4. Use the chown utility to change owners of home directories.
  5. Start RStudio Workbench.
  6. Users log in with LDAP/AD credentials.

    Note

    User sessions will be persisted, but old home directory locations may be cached in the environment variable $HOME. Restarting R sessions should resolve the issue.

Example Configuration#

  • Suppose Suzy has an AD account with username suzy_ad and the local Linux username suzy_local.
  • After configuring AD, Suzy's account will be fetched from AD and the following will be the case:

    Terminal
    $ echo ~suzy_local
    /home/suzy_local
    $ echo ~suzy_ad
    /home/suzy_ad
    

  • You'll need to migrate Suzy's home directory and chown the contents:

    Terminal
    # Move user directory contents
    $ rm -r /home/suzy_ad/ && mv /home/suzy_local /home/suzy_ad
    # Note: colon following username changes user and group
    $ chown -R suzy_ad: /home/suzy_ad/
    

For users whose usernames will not change, you do not need to move user home directories, but you may still need to chown home directories to account for UID changes.

UIDs and Load Balancing/High Availability

If you have a cluster of multiple RStudio Workbench nodes, UIDs must match across the nodes and should be determined by LDAP/AD as opposed to determined automatically at user creation time.

Migration to SSO with LDAP/AD#

If you are going from manual user provisioning and local Linux authentication to user provisioning with LDAP/AD and SSO authentication:

  1. First, follow the steps above to configure LDAP/AD authentication.
  2. Then, configure SSO (SAML/OIDC) in RStudio Workbench.

RStudio Workbench matches SSO identities to system users and home directories via username, so the SSO identity must match the LDAP/AD username.

The SSO attribute used as the identity is configurable. It defaults to NameID for SAML and to preferred_username for OIDC.

Migration from local Linux accounts to SSO without LDAP/AD#

If you are migrating from local Linux accounts to SSO (SAML/OIDC) without configuring LDAP/AD for user provisioning, it is easiest to leave UIDs the same and change usernames to match SSO identities and (optionally) home directories.

The SSO attribute used as the identity is configurable. It defaults to NameID for SAML and to preferred_username for OIDC.

The steps for this migration would be as follows:

  1. Stop RStudio Workbench.
  2. Update existing local Linux usernames to match SSO identities.
  3. (Optional) Change home directories in definitions in /etc/passwd and move home directories to the new location.
  4. Configure RStudio Workbench with SSO.
  5. Start RStudio Workbench.
  6. Users can log in with SSO.

    Note

    User sessions will be persisted, but old home directory locations may be cached in the environment variable $HOME. Restarting the R session should solve the issue.

Example Configuration#

  • If Suzy has the SSO identity suzy and already has a local account named suzy and the home directory /home/suzy, no changes would be needed before configuring SSO.
  • If Suzy instead had the local account suzy_local and the home directory /home/suzy_local, you would need to:

    • Change her local username to suzy.
    • (Optionally) her home directory to /home/suzy as below:

    Terminal
    # Change username
    $ usermod -l suzy suzy_local
    # Move user directory contents
    $ mv /home/suzy_local/ /home/suzy/
    # Note: no chown needed because no changes to UID
    

Migration to local Linux accounts#

To migrate from any other authentication configuration to local Linux accounts, you will need to:

  1. Disable the integration with the outside system.
  2. Create a local password for the user.

No other changes are necessary for existing accounts.

New accounts need to be manually created on the server.

Example Configuration#

  • To create a password for Suzy with account suzy:

    Terminal
    $ sudo passwd suzy
    

This prompts you to enter a password so it doesn't display on the command line in plain text.


  1. We have renamed RStudio Server Pro to RStudio Workbench. This change reflects the product’s growing support for a wide range of different development environments. Please see our official Announcement and review our FAQ regarding the name change from RStudio Server Pro to RStudio Workbench. 

Back to top