Posit Connect supports migrating authentication providers / switching from one authentication provider to another. The process requires understanding the authentication providers that you are switching FROM and TO, as well as utilizing the Connect usermanager CLI.

In general, most of the user migration process hinges on where you are heading "to," and not necessarily where you are coming from.

There are two approaches to changing authentication providers:

- Create a new server and then migrate important content from the old server to the new server

- Update the existing server to use the new authentication mechanism

This article discusses the second approach, which requires changing the Posit Connect server configuration and then updating users to use the new authentication mechanism.

Below, we will walk through a few examples of migrating users. They will illustrate the appropriate steps to migrate from one authentication provider to another. Namely:

- List existing users with usermanager

- Update RStudio Connect server configuration to use the new authentication mechanism

- Update user identity to reference the new authentication mechanism

NOTE:

- This guide assumes Connect version 1.7.4 or later

- If you are using a SQLite database, Connect must be stopped in order to use the usermanager CLI

Example: From LDAP to SAML

In this example, we have a Connect server that is using LDAP authentication and already has content deployed to it.

List Existing Users

The first step is to list your existing user accounts. This can be done using the usermanager CLI

# /opt/rstudio-connect/bin/usermanager list
...
2019/05/14 16:31:37 Listing users
GUID                                 ID Username First Last    Email             Role          DN                                        UniqueID
----                                 -- -------- ----- ----    -----             ----          --                                        --------
5c0e9e99-09b2-4507-b5da-57b7b2f2294a 4  jen      Jen   Juniper jen@example.org   publisher     cn=jen,dc=support,dc=example,dc=org       Mjc4NDdlNjItZWE2NC0xMDM4LTlkOTctNmYzOTg0YTNiMDRh
42166d51-86a9-48dc-a800-68bf8b4ace14 3  john     John  Doe     john@example.org  publisher     cn=john,dc=finance,dc=example,dc=org      Mjc4M2Q1NzAtZWE2NC0xMDM4LTlkOTUtNmYzOTg0YTNiMDRh
802c14ee-2d6c-4c9b-ac06-bf46e3e2fdb4 2  julie    Julie Jolly   julie@example.org publisher     cn=julie,dc=engineering,dc=example,dc=org Mjc4MmQ1ZDAtZWE2NC0xMDM4LTlkOTEtNmYzOTg0YTNiMDRh
bad36030-800b-45ba-b577-27310cf1795b 1  test     Test  Tester  test@example.org  administrator cn=test,dc=support,dc=example,dc=org      Mjc4NGJhZGEtZWE2NC0xMDM4LTlkOTgtNmYzOTg0YTNiMDRh

You can see in this output that we are using LDAP for our authentication mechanism, and are following recommendation to use something other than DN as our UniqueIdAttribute. Using the DN as the unique ID attribute may result in unexpected behavior because DNs can change over time  and so prevent users from being able to log in.

The two most important attributes in the above table are the GUID and the UniqueID.

The GUID uniquely identifies a user within Posit Connect and UniqueID uniquely identifies a user with the authentication provider. You will use both in the coming steps.

Update RStudio Connect configuration

Now we need to update Posit Connect to use SAML instead of LDAP. We will edit the /etc/rstudio-connect/rstudio-connect.gcfg configuration file. This means where we had:

[Authentication]
Provider = ldap

[ LDAP "My LDAP Server" ]
Logging = true
; ldap attributes

We now have:

[Authentication]
Provider = saml

[SAML]
Logging = true
; saml attributes

Then we restart Posit Connect.

sudo systemctl restart rstudio-connect

Migrate Users

After Posit Connect restarts, we might notice that new users join the server easily. However, if a user tries to join the server whose username is already taken, you will see log messages like

2019/05/14 17:22:47 /connect/src/connect/auth/providers/saml/saml.go:849: (saml) Treating as new user
2019/05/14 17:22:47 SAML handling error trying to validate the username jen: The requested username is already in use.

jen already exists (her user was created with LDAP authentication), and so we need to update her Unique Identifier to match what it should be in our SAML identity provider. In SAML, this is NameID by default (although it can be configured to be a different attribute).

jen's NameID / UniqueID is 1004, so the following usermanager command will migrate her RStudio Connect user from LDAP to SAML

# /opt/rstudio-connect/bin/usermanager alter --users --user-guid <GUID> --new-unique-id <NewUniqueID>

/opt/rstudio-connect/bin/usermanager alter --users --user-guid 5c0e9e99-09b2-4507-b5da-57b7b2f2294a --new-unique-id 1004

...

2019/05/14 18:29:40 Field    Old                                              New
2019/05/14 18:29:40 UniqueID Mjc4NDdlNjItZWE2NC0xMDM4LTlkOTctNmYzOTg0YTNiMDRh 1004
2019/05/14 18:29:40 --- Staged Changes: user 'jen' ---
2019/05/14 18:29:40 To commit these changes, press ENTER. To abort, use CTRL-C...

2019/05/14 18:29:42 The user 'jen' had its unique ID replaced with '1004' .
2019/05/14 18:29:42 Modified user 'jen'

Once complete, jen should be able to log into Posit Connect using SAML authentication. Repeat this step for each user to complete the migration process to a new authentication provider.

Example: To PAM

Most of the user migration process hinges on where you are heading "to," and not necessarily where you are coming from. We will follow the same three steps shown above for LDAP to SAML:

1. List existing users
2. Update Posit Connect configuration
3. Migrate users

List Existing Users

We will list our existing users and save that information to a file for later reference. Keep an eye on the users' GUIDs and UniqueIds. The GUIDs are how we reference unique users, and the UniqueId is what we will change to match PAM authentication.

# /opt/rstudio-connect/bin/usermanager list
...
GUID                                 ID Username First Last Email           Role          UniqueID
----                                 -- -------- ----- ---- -----           ----          --------
77019977-b269-4f3a-afa8-69783f6dc8c5 2  sue      Sue   So   sue@example.com viewer        p30a3d1c75286214f
48c6580b-8151-49fe-b911-0fa3a202661a 1  jim      Jim   Bo   jim@example.com administrator pb0da9915d1998c41

NOTE: Do not be concerned if your UniqueIds look different, or if you have a "DN" field (and are currently using LDAP authentication). We will be overwriting these UniqueId attributes soon. The old values are mostly illustrative as an example of "which users are not ready to log in with the new authentication system yet"

Update Posit Connect configuration

To update the Posit Connect configuration, we simply change the authentication provider to pam (the default is password).

[Authentication]
Provider = pam

Then we restart Posit Connect:

sudo systemctl restart rstudio-connect

Migrate Users

After Posit Connect restarts, we might notice that new users join the server easily. However, if a user tries to join the server whose username is already taken, you will see log messages like

2019/11/04 21:33:01 pam: Failed to authenticate jim against PAM service rstudio-connect: The requested username is already in use.

Since the user "jim" already exists, we will need to "migrate" this user to the new authentication method. In order to do this, we will update the user's Unique ID to match the following pattern:

_pam_u_<username>

Where <username> is the linux username in question. For our case, this is "jim." So we will update the user as follows:

/opt/rstudio-connect/bin/usermanager alter --users --user-guid 48c6580b-8151-49fe-b911-0fa3a202661a --new-unique-id _pam_u_jim

...
2019/11/04 21:38:51 Field     Old                New
2019/11/04 21:38:51 UniqueID  pb0da9915d1998c41  _pam_u_jim
2019/11/04 21:38:51 --- Staged Changes: user 'jim' ---
2019/11/04 21:38:51 To commit these changes, press ENTER. To abort, use CTRL-C...

2019/11/04 21:39:21 The user 'jim' had its unique ID replaced with '_pam_u_jim' .
2019/11/04 21:39:21 Modified user 'jim'

Then the user "jim" should be able to log into the server using PAM Authentication! Repeat for all users, and you should be good to go.

NOTE that the Posit Connect username and the linux username do NOT need to match. You can see that this is the case for the user "sue", whose linux username is "sue_user":

/opt/rstudio-connect/bin/usermanager alter --users --user-guid 77019977-b269-4f3a-afa8-69783f6dc8c5 --new-unique-id _pam_u_sue_user

...
2019/11/04 21:43:24 Field    Old               New
2019/11/04 21:43:24 UniqueID p30a3d1c75286214f _pam_u_sue_user
2019/11/04 21:43:24 --- Staged Changes: user 'sue' ---
2019/11/04 21:43:24 To commit these changes, press ENTER. To abort, use CTRL-C...

2019/11/04 21:43:25 The user 'sue' had its unique ID replaced with '_pam_u_sue_user' .
2019/11/04 21:43:25 Modified user 'sue'

It is worth mentioning that "sue_user" is the username that this user will use to log into RStudio Connect.

Complete

When finished, we can see that our users have been updated appropriately by looking at the list command again.

# /opt/rstudio-connect/bin/usermanager list

...

GUID                                 ID Username First Last Email           Role          UniqueID
----                                 -- -------- ----- ---- -----           ----          --------
77019977-b269-4f3a-afa8-69783f6dc8c5 2  sue      Sue   So   sue@example.com viewer        _pam_u_sue_user
48c6580b-8151-49fe-b911-0fa3a202661a 1  jim      Jim   Bo   jim@example.com administrator _pam_u_jim

Tips

• The --yes option can be used for the usermanager if you want to script the migration for all of your users. Please be careful when using this option!!
• If you are doing a different type of migration than shown above, the main point to focus on is getting the UniqueId attribute set right.
• Test with one user and be sure that login works before proceeding to others
• To batch all users together, we recommend taking the output of usermanager list and using a spreadsheet, R script, python script, etc. to build a shell script of the necessary commands. Then you can execute the shell script to migrate all users at once.
  • We recommend saving the shell script and its output for future reference
  • NOTE: to have a non-interactive shell script, you will need the --yes flag (which should be used with caution)
  • Be sure to run usermanager list afterwards to sanity check your changes

Troubleshooting

Base64 Encoding

You may notice that the UniqueID used by LDAP is base64 encoded. This is because LDAP and some other authentication providers can use binary data as a unique identifier. In some cases when using LDAP or Proxied Authentication, you will need to use the --base64-unique-id flag for the usermanager alter command. 

For instance,

/opt/rstudio-connect/bin/usermanager alter --users --user-guid <GUID> --base64-unique-id --new-unique-id <NewUniqueID>

The --base64-unique-id flag is only needed when migrating to or setting unique IDs for:

- LDAP authentication with a UniqueIDAttribute other than the default (DN)

- Proxied authentication with a UniqueIDAttribute other than the default (username)

Some other related flags are --force-hex and --force-ms-guid.