Changing Authentication Provider (Migration)

The decision to change which authentication provider is configured for Posit 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 still exist).

There are use cases, however, where changing the authentication provider is necessary. One of the most common ones is when 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 Connect in a production environment.

If maintaining existing content is not important, the simplest approach is to completely purge and reinstall Connect. See the Purging Posit Connect section for instructions.

Uniquely identifying users

Among the data that Posit 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 Posit Connect Server API to create new user records ahead of time.

Depending on your knowledge about the new provider and what they will use for users’ Unique ID, there are three options for mapping Unique IDs from the old provider to the new one:

Manually assign the Connect user identifier as the new Unique ID

Avoiding this user creation is the most straightforward choice, but requires 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 Connect.

  2. Use the list command of the usermanager tool to discover the identifier for each user in 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 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 Connect to use the new authentication provider.

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

Create new user records using the Connect Server API

Once Posit Connect has been reconfigured with the new authentication provider, you can use the 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 Posit 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 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.

Log in to Connect under the new authentication provider

Or, you can require that the user log in to Connect under the new authentication provider. This creates 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 Posit Connect so that new user records are not automatically created, you 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 Connect.

  2. Reconfigure Connect to use the new authentication provider.

  3. Restart Connect.

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

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

  6. Stop Connect.

  7. Use the list command of the usermanager tool to discover the identifier for the old record for the user in 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 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 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 Posit 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.

Connect issues 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 labels 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 Posit 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

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, Posit Connect will see this as a new user. In this case, you need to use the usermanager transfer command to move everything from jim to james.

Changing X-Auth-Username responses for a user under Proxied authentication

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

Mix of local and remote groups in LDAP

Having both local and remotely managed groups in LDAP is NOT SUPPORTED. If you have made a switch from one group management mode to another without removing or transferring the existing groups, Posit Connect will issue a warning message stating the number and type of groups in violation of support.

Why? Allowing only one mode (remote or local) active at a time makes it possible to have a single source of truth in identity and permission management. Having mixed group management types active concurrently (some in local mode and others in remote mode) works against this security model.

Use the usermanager CLI tool align-ldap-groups command to change groups over to a target (remote or local) mode.