Authentication Migration

It is possible to migrate between the supported authentication mechanisms.

Posit Workbench can be configured to authenticate using local Linux accounts, LDAP/Active Directory, SAML, or OpenID Connect (OIDC). See authenticating users for a full list of the authentication mechanisms supported by Workbench.

Each user on 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.

Migration from local Linux accounts to LDAP/AD

If you are migrating to LDAP/AD from local Linux accounts, local user accounts are created by PAM when a user logs in to Workbench with their LDAP/AD credentials.

Ensure that:

The existing PAM configuration is configured for PAM and provisioning
Workbench is configured with PAM Sessions

The steps are as follows:

Stop Workbench.
Configure LDAP/AD authentication with Workbench.
- See the Active Directory section for instructions on configuring LDAP/AD with Workbench.
Move all files from old home directories to new ones.
Use the chown utility to change owners of home directories.
Start Workbench.
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
$ sudo rm -r /home/suzy_ad/ && sudo mv /home/suzy_local /home/suzy_ad
# Note: colon following username changes user and group
$ sudo 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.

Warning

If you have a cluster of multiple 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

To migrate to SSO with LDAP/AD, follow the steps above to configure LDAP/AD authentication if not already configured. Then, configure SAML or OIDC.

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 Username for SAML and to preferred_username for OIDC.

Important

If PAM was used with Kerberos, please note that the credential forwarding functionality offered by Kerberos is only possible with PAM and it cannot be leveraged directly by Workbench when using SSO.

Migration from local Linux accounts to SSO without LDAP/AD

Your local system accounts currently used with PAM can be used for Single Sign-On (SSO) authentication with SAML or OpenID without configuring LDAP/AD for user provisioning. In this scenario, it is easiest to leave UIDs the same and change usernames to match SSO identities (if necessary) and (optionally) home directories.

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

The steps for this migration would be as follows:

Stop Workbench.
Update existing local Linux usernames to match the SAML attribute or OpenID claim for username from your Identify Management system if required.
(Optional) Change home directories in definitions in /etc/passwd and move home directories to the new location.
Configure Workbench with the appropriate SSO authentication mechanism.
Start Workbench.
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
$ sudo usermod -l suzy suzy_local
# Move user directory contents
$ sudo 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:

Disable the integration with the outside system.
Create local accounts for existing users.

New accounts need to be manually created on the server.

Note

When creating local accounts for existing users, ownership of existing files and directories for that user may need to be transferred to the new account.

Example Configuration

Suppose Suzy has an AD account with username suzy
After disabling LDAP/AD, a local account should be created for Suzy.
```
Terminal
```
```
$ sudo useradd suzy
$ sudo passwd suzy
```
The new local account for suzy will have a different UID than the previous AD account, so you will need to change ownership of the home directory:
```
Terminal
```
```
$ sudo chown -R suzy: /home/suzy
```
There may be other files and directories owned by suzy that need to be changed as well. You can find them with:
```
Terminal
```
```
$ sudo find / -user suzy
```
It may be desirable instead to use the same uid as the previous account so that ownership of files and directories does not need to be transferred.
```
Terminal
```
```
$ sudo useradd -u <uid> suzy
$ sudo passwd suzy
```

Migrating from proxied authentication

Your local system accounts currently used with Proxied authentication can be used for Single Sign-On (SSO) authentication with SAML or OpenID. Ensure that:

If Workbench is placed under a different path by the proxy (e.g., example.com/rstudio), be sure to check the “Proxy Considerations” sections under SAML Single Sign-On Authentication or OpenID Connect Authentication for additional options your proxy or Workbench configuration may need.
Workbench is configured with the appropriate SSO authentication mechanism.
The configured SAML attribute or OpenID claim for username match the names of your existing local system accounts as they were sent by the proxy in the HTTP header for username.

Migrating to proxied authentication

Warning

This migration is not recommended unless none of the other existing authentication mechanisms are sufficient for your organization’s needs.

If migrating from PAM, you can follow the same recommendations listed above for SSO, noting that the HTTP header for username must match existing accounts. If migrating from SAML or OpenID, the same observation on the HTTP header for username applies.

Note

When using proxied authentication, usernames can be rewritten to match existing accounts on the system. See Rewriting usernames for more information.

Migrating from Google accounts

Migrating from Google accounts is similar to migrating from PAM to SSO, or [Migrating to PAM].

Important

Google accounts have been deprecated and we strongly recommend against migrating to this authentication.

Note

If you are currently using Google accounts for authentication, the migration from Google accounts to OpenID using Google itself as the OpenID provider is not yet supported. We recommend to keep using Google accounts or migrating to some other non-Google SSO authentication.