Configuration
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.
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.conf
can 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
.
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:
Create a custom
authselect
profile. If you are currently usingsssd
for user provisioning, you can base the new profile on thesssd
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
Enable the
pwb
module in the new profile. Edit the/etc/authselect/custom/pwb/nsswitch.conf
file and add thepwb
entry to the end of thepasswd
,group
, andshadow
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"}
Enable the new profile. To enable the new profile, run the following command:
terminal
$ sudo authselect select custom/pwb with-mkhomedir
To make sure the
pam_oddjob_mkhomedir
module is present andoddjobd
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.
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
Configure
pwb
as an NSS module in/etc/nsswitch.conf
. Thepwb
entry should be added at the end of thepasswd
,group
, andshadow
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.
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 isfalse
.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 theuser-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.