Configuration

rserver.conf

To enable user provisioning, make the following changes in the /etc/rstudio/rserver.conf file:

Set the configuration option user-provisioning-enabled to 1:
```
rserver.conf
```
```
user-provisioning-enabled=1
```
Restart Posit Workbench:
```
terminal
```
```
sudo rstudio-server restart
```

Configuring the minimum starting UID for provisioned users

By default, Workbench starts provisioning users with a minimum user ID (UID) of 1000. To change this, set the user-provisioning-start-uid configuration option in the /etc/rstudio/rserver.conf file.

For example, to start provisioning users with a minimum UID of 2000, set the following configuration option in the rserver.conf file:

rserver.conf

user-provisioning-start-uid=2000

After you set this option and restart Workbench, Workbench assigns new users the next available UID, starting from the value specified in this configuration option.

The minimum supported value for this configuration option is 1000.

Configuring the minimum starting GID for provisioned groups

By default, Workbench provisions groups starting with a minimum group ID (GID) of 1000. To change this, in the /etc/rstudio/rserver.conf file, set the group-provisioning-start-gid configuration option.

For example, to start provisioning groups with a minimum GID of 2000, add the following setting to /etc/rstudio/rserver.conf:

rserver.conf

group-provisioning-start-gid=2000

After you set this option and restart Workbench, Workbench assigns new groups the next available GID, 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 at /etc/rstudio/workbench-nss.conf. This file is required by the NSS module and 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 only exception is for sessions running in containerized environments. In these cases, 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. You must create the configuration file at /etc/rstudio/workbench-nss.conf. You must not create it anywhere else on the system.

To use Workbench configuration files in a separate location, configure XDG_CONFIG_DIRS to the appropriate directory. For example, if configuration files are in a shared location, set the XDG_CONFIG_DIRS value to:

XDG_CONFIG_DIRS=/etc:/shared/etc

In this example, using XDG_CONFIG_DIRS allows shared configuration files to be placed in /shared/etc/rstudio, and workbench-nss.confcan be placed in /etc/rstudio.

The workbench-nss.conf file could 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>

`server-address`

The server-address option specifies the Workbench server URL the NSS module uses to query the Workbench System for Cross-domain Identity Management (SCIM) API.

When Workbench generates the workbench-nss.conf file, it automatically sets this option to the Workbench user service socket path. This path resides in the Workbench run-time directory, which Workbench determines based on theserver-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 not running Workbench (such as Slurm compute nodes), you must set the server-address configuration option to the Workbench server URL. For example: https://workbench.example.com

`admin-token-path` and `user-token-path`

The admin-token-path and user-token-path options specify the locations of the authentication tokens the NSS module uses.

When Workbench generates the workbench-nss.conf file, it automatically sets these options to the default locations /etc/rstudio/admin-token and /etc/rstudio/user-token. For more information on these tokens, see the NSS tokens section.

`verify-ssl-certs`

The verify-ssl-certs option specifies whether the NSS module should verify the Workbench server SSL certificates. By default, this option is set to 1 to verify SSL certificates.

If you are using a self-signed certificate, you might 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, you must configure the NSS module manually on some Linux distributions, such as RHEL 8, RHEL 9, and RHEL 10.

To configure the NSS module in these cases, create a custom authselect profile and enable the pwb NSS module, as described in the steps below.

Create a custom authselect profile. If you are currently using sssd for user provisioning, you can base the new profile on the sssd profile by running:
```
terminal
```
```
sudo authselect create-profile pwb --base-on=sssd
```
Otherwise, create the new profile based on the minimal profile by running:
```
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 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"}

Enable the new profile by running the following command:

terminal

sudo authselect select custom/pwb with-mkhomedir

Verify that the pam_oddjob_mkhomedir module is present and oddjobd service is enabled and active by running:
```
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. By default, NSCD also caches information from the passwd and group databases, but this can cause issues with Workbench user provisioning.

You can prevent NSCD from caching passwd and group information to ensure the Workbench NSS module handles the NSS lookups for user information. Disabling these caches should not affect system performance, as Workbench user provisioning implements its own caching mechanism.

To prevent NSCD from caching information from the passwd and group databases, follow these steps:

Add the following lines to the /etc/nscd.conf file:

nscd.conf

enable-cache passwd no
enable-cache group no

Restart the NSCD service:
```
terminal
```
```
sudo systemctl restart nscd
```

Disabling NSCD caching is also the recommended approach for systems that use sssd. See documentation on Using NSCD with SSSD for more information.

Home directories

Workbench user provisioning requires a mechanism for creating user home directories configured on the system. We suggest using the PAM module pam_mkhomedir, which can create user home directories automatically when a user logs in for the first time.

Note

In most cases, PAM sessions must be enabled in Workbench to use pam_mkhomedir module. See the PAM Sessions & Kerberos section of this guide for more information on how to configure Workbench to use PAM sessions.

To use pam_mkhomedir for creating user home directories, follow these steps:

Install and configure the pam_mkhomedir module in the system. For additional informaton on the module, see the documentation for pam_mkhomedir(8) - Linux man page.
Add the following configuration to the PAM profile used Workbench users:
```
session required pam_mkhomedir.so skel=/etc/skel umask=0077
```

Root home directory

If your Workbench configuration needs to support user home directories in a location other than /home, use the configuration option user-homedir-path to specify the root directory for user home directories.

Only use this option when you have also enabled the user-provisioning-enabled configuration option.

rserver.conf

user-homedir-path=/mnt/home

NSS tokens

The NSS module requires two tokens to be generated and installed on the system: the admin token and the user token. The NSS module uses these tokens to authenticate requests to the Workbench SCIM API.

When you enable user provisioning, Workbench automatically generates these tokens on startup and installs them to the default locations /etc/rstudio/admin-token and /etc/rstudio/user-token. See the Custom token paths section for information on how to configure these paths.

The NSS module uses the admin token when the process that loaded it is running with root privileges. If the process is not running as root, the NSS module uses the user token instead. 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. To use a different location for these tokens (for example, to share them across multiple nodes), 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 use Slurm compute nodes with Workbench, you must install and configure the NSS module on each node. This allows the session components to use the NSS module to retrieve user information. Follow these steps to configure the NSS module on Slurm compute nodes:

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. Add the pwb entry at the end of the passwd, group, and shadow databases:
```
nsswitch.conf
```
```
passwd:         files systemd pwb
group:          files systemd pwb
shadow:         files pwb
```
If you are running on a RHEL system, 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 for users:

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

Similarly, Workbench supports the following SCIM extension attributes for groups:

posixGroupId: The group’s posix group id, which is the local group ID associated with the group in Workbench.
posixGroupName: The group’s posix group name, which is the local group name associated with the group in Workbench.

By default, the standard attributes from both the identity provider (IdP) and Workbench determine these values. You can add custom attributes to the user profile in the IdP, and set these values when assigning users to the Workbench application.

Okta

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

Microsoft Entra ID

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