Configuration

Workbench

rserver.conf

To enable user provisioning, in the file /etc/rstudio/rserver.conf, set the configuration option user-provisioning-enabled to 1:

rserver.conf
user-provisioning-enabled=1

After enabling this option, restart Workbench:

terminal
$ sudo rstudio-server restart

Configuring the minimum starting UID for provisioned users

By default, Workbench starts provisioning users with a minimum UID of 1000. This can be changed by setting the configuration option user-provisioning-start-uid in the file /etc/rstudio/rserver.conf. For example, to start provisioning users with a minimum UID of 2000, set the following configuration option in the file /etc/rstudio/rserver.conf:

rserver.conf
user-provisioning-start-uid=2000

After setting this option and restarting Workbench, new users are provisioned with the next available UID, starting from the value specified in this configuration option.

The minimum supported value for this configuration option is 1000.

workbench-nss.conf

Workbench automatically generates the workbench-nss.conf configuration file required by the NSS module at /etc/rstudio/workbench-nss.conf. This file must be created on all nodes requiring the NSS library to access user information via system calls, such as Workbench nodes and Slurm compute nodes. The only exception is sessions running in containerized environments, as these sessions should use the launcher-sessions-create-container-user option.

Note

The Workbench NSS module does not adhere to environment variables such as XDG_CONFIG_DIRS and RSTUDIO_CONFIG_DIR, meaning that the configuration file must be created at /etc/rstudio/workbench-nss.conf. It cannot be created anywhere else on the system.

One strategy for using Workbench configuration files in a separate location, such as when configuration files are in a shared location, is to set XDG_CONFIG_DIRS as such:

XDG_CONFIG_DIRS=/etc:/shared/etc

That way shared configuration files can be placed in /shared/etc/rstudio and workbench-nss.confcan be placed in /etc/rstudio.

This file may contain the following configuration options:

workbench-nss.conf
server-address=https://<workbench-hostname>|unix:<workbench-user-service-socket-path>
admin-token-path=/etc/rstudio/admin-token
user-token-path=/etc/rstudio/user-token
verify-ssl-certs=<1|0>

The server-address configuration option specifies the URL of the Workbench server that the NSS module uses to query the Workbench SCIM API. When generating the workbench-nss.conf file, Workbench automatically sets this option to the socket path of the Workbench user service, located in Workbench’s run-time directory informed by the server-data-dir configuration option. The default value is: unix:/var/run/rstudio-server/rstudio-rserver/user-service.socket.

Important

When configuring workbench-nss.conf on nodes that are not running Workbench, such as Slurm compute nodes, the server-address configuration option must be set to the URL of the Workbench server. For example, https://workbench.example.com.

The admin-token-path and user-token-path options specify the locations of the authentication tokens used by the NSS module. When generating the workbench-nss.conf file, Workbench automatically sets these options to their default locations of /etc/rstudio/admin-token and /etc/rstudio/user-token. For more information on these tokens, see the NSS tokens section below.

The verify-ssl-certs option specifies whether the NSS module should verify the SSL certificates of the Workbench server. By default, this option is set to 1 to verify SSL certificates. If you are using a self-signed certificate, you may need to set this option to 0 to disable SSL certificate verification.

nsswitch.conf

On most Linux distributions, the NSS module is installed and configured by default. However, the NSS module must be configured manually on some Linux distributions, such as RHEL 8 and RHEL 9. This is done by creating a custom authselect profile and enabling the pwb NSS module, as described in the steps below:

  1. Create a custom authselect profile. If you are currently using sssd for user provisioning, you can base the new profile on the sssd profile:

    terminal
    $ sudo authselect create-profile pwb --base-on=sssd

    Otherwise, create the new profile based on the minimal profile:

    terminal
    $ sudo authselect create-profile pwb --base-on=minimal

  2. Enable the pwb module in the new profile. Edit the /etc/authselect/custom/pwb/nsswitch.conf file and add the pwb entry to the end of the passwd, group, and shadow databases, for example:

    nsswitch.conf
    passwd:     files {if "with-altfiles":altfiles }systemd pwb {exclude if "with-custom-passwd"}
group:      files {if "with-altfiles":altfiles }systemd pwb {exclude if "with-custom-group"}
shadow:     files pwb                                       {exclude if "with-custom-shadow"}

  3. Enable the new profile. To enable the new profile, run the following command:

    terminal
    $ sudo authselect select pwb --with-mkhomedir

    To make sure the pam_oddjob_mkhomedir module is present and oddjobd service is enabled and active:

    terminal
    $ systemctl enable --now oddjobd.service

NSCD caching

The Name Service Cache Daemon (NSCD) provides a cache for the most common name service requests, such as hosts and services requests. By default, NSCD also caches information from the passwd and group databases. This can cause issues with Workbench user provisioning, as the Workbench NSS module may not be used to retrieve user information from the Workbench SCIM API.

To prevent NSCD from caching information from the passwd and group databases, add the following lines to the /etc/nscd.conf file:

nscd.conf
enable-cache passwd no
enable-cache group no

After making these changes, restart the NSCD service:

terminal
$ sudo systemctl restart nscd

This prevents NSCD from caching information from the passwd and group databases, ensuring that NSS lookups for user information on the system are handled by the Workbench NSS module. System performance should not be affected by disabling these caches, as Workbench user provisioning implements its own caching mechanism. Disabling NSCD caching is also the recommended approach for systems that use sssd. See Using NSCD with SSSD for more information.

Home directories

Workbench user provisioning requires a mechanism for creating user home directories to be configured on the system. There are various ways to create home directories for users and one suggested method is to use the PAM module pam_mkhomedir.

The pam_mkhomedir module can be used to create user home directories on the fly when a user logs in for the first time. It must be installed and configured in the system. Reference pam_mkhomedir(8) - Linux man page for additonal information on this module.

The following configuration must be added to the PAM profile that is used by Workbench users:

session required pam_mkhomedir.so skel=/etc/skel umask=0077

In most cases, PAM sessions must be enabled in Workbench to use this module. See this guide’s PAM Sessions & Kerberos section for more information on how Workbench can be configured to use PAM sessions.

Root home directory

For Workbench configurations that need to support user home directories in a location other than /home, the configuration option user-homedir-path can be used to specify the root directory where user home directories are created. This option is only used when the configuration option user-provisioning-enabled is enabled.

rserver.conf
user-homedir-path=/mnt/home

NSS tokens

The NSS module requires two tokens to be generated and installed on the system. These tokens are used by the NSS module to authenticate requests to the Workbench SCIM API. When user provisioning is enabled, Workbench automatically generates these tokens on startup and installs them on the system. By default, the tokens are installed to /etc/rstudio/admin-token and /etc/rstudio/user-token. See the Custom token paths section below for information on how to configure these paths.

The admin token is used by the NSS module when the process that loaded the module is running effectively as the root user. The user token is used by the NSS module when the process that loaded the module is not running effectively as the root user. This controls access to the user’s shadow entry.

Custom token paths

By default, the NSS module looks for the admin and user tokens in /etc/rstudio/admin-token and /etc/rstudio/user-token. If you wish to use a different location for these tokens, for instance, to share them across multiple nodes, you can specify the token paths in the file /etc/rstudio/workbench-nss.conf:

workbench-nss.conf
server-address=https://<workbench-hostname>
admin-token-path=/mnt/shared/admin-token
user-token-path=/mnt/shared/user-token

Workbench session components for Slurm compute nodes

If you are using Slurm compute nodes with Workbench, you must install and configure the NSS module on each node. This is required so the session components can use the NSS module to retrieve user information.

  1. Make a symlink from /usr/lib/rstudio-server/bin to a system library location, such as /usr/lib/x86_64-linux-gnu on debian systems or /usr/lib64 on RHEL systems:

    terminal
    $ sudo ln -s /usr/lib/rstudio-server/bin/libnss_pwb.so /usr/lib/x86_64_linux_gnu/libnss_pwb.so.2

  2. Configure pwb as an NSS module in /etc/nsswitch.conf. The pwb entry should be added at the end of the passwd, group, and shadow databases:

    nsswitch.conf
    passwd:         files systemd pwb
group:          files systemd pwb
shadow:         files pwb

    On RHEL systems, see the nsswitch.conf section above for more information on how to configure the NSS module.

  3. Create the /etc/rstudio/workbench-nss.conf file. See the workbench-nss.conf section above for more information on how to configure this file.

Adding Workbench attributes to identity providers

Workbench supports the following SCIM extension attributes:

  • admin: A boolean value indicating whether the user is a Workbench administrator or not. By default this is false.
  • posixUserName: The user’s posix username. This is the username that is used when starting sessions in Workbench.
  • posixUserId: The user’s posix user ID. This is the local user ID that is associated with the user on Workbench.
  • homeDirectory: The user’s home directory. By default this uses the value of the user-homedir-path configuration option in Workbench.

By default, these fields are derived from the user’s standard attributes in the identity provider and Workbench’s configuration. However, it is possible to add custom attributes to the user profile in the identity provider and set these values when assigning users to the Workbench application.

Okta

See the Add custom attributes to an Okta user profile section of Okta’s documentation for more information on adding custom user attributes in Okta.

Microsoft Entra ID

See the Customize user provisioning attribute mappings tutorial in Microsoft’s documentation for more information on adding custom user attributes in Microsoft Entra ID.

Back to top