RStudio 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 RStudio Connect usermanager CLI.
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 RStudio Connect server configuration and then updating users to use the new authentication mechanism.
Below, we will walk through an example of migrating users from LDAP authentication to SAML authentication. It 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
- This guide assumes RStudio Connect version 1.7.4 or later
- If you are using a SQLite database, RStudio Connect must be stopped in order to use the usermanager CLI
Example: From LDAP to SAML
In this example, we have an RStudio 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 firstname.lastname@example.org publisher cn=jen,dc=support,dc=example,dc=org Mjc4NDdlNjItZWE2NC0xMDM4LTlkOTctNmYzOTg0YTNiMDRh
42166d51-86a9-48dc-a800-68bf8b4ace14 3 john John Doe email@example.com publisher cn=john,dc=finance,dc=example,dc=org Mjc4M2Q1NzAtZWE2NC0xMDM4LTlkOTUtNmYzOTg0YTNiMDRh
802c14ee-2d6c-4c9b-ac06-bf46e3e2fdb4 2 julie Julie Jolly firstname.lastname@example.org publisher cn=julie,dc=engineering,dc=example,dc=org Mjc4MmQ1ZDAtZWE2NC0xMDM4LTlkOTEtNmYzOTg0YTNiMDRh
bad36030-800b-45ba-b577-27310cf1795b 1 test Test Tester email@example.com 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 RStudio 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 RStudio Connect to use SAML instead of LDAP. We will edit the /etc/rstudio-connect/rstudio-connect.gcfg configuration file. This means where we had:
Provider = ldap
[ LDAP "My LDAP Server" ]
Logging = true
; ldap attributes
We now have:
Provider = saml
Logging = true
; saml attributes
Then we restart RStudio Connect.
After RStudio 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 RStudio Connect using SAML authentication. Repeat this step for each user to complete the migration process to a new authentication provider.
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.
/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.