PAM Authentication

Note

For the broader picture of how authentication, PAM sessions, and user provisioning work together to grant users access to Workbench, see Managing user access to Workbench.

PAM basics

Local system accounts used by PAM must follow the system conventions for usernames. For example, usernames are case-sensitive. The allowable characters in a username vary. Some Linux versions allow only lower-case letters, digits and hyphens. When using LDAP or Active Directory systems may allow underscore, period and the @ symbol for email addresses.

When a system supports more than one username for the same UID, Posit Workbench will allow the user to login with any alias. After login, the primary username will be used to identify the user to the system. This is the username returned by the system for the user’s UID.

PAM profiles are located in the /etc/pam.d directory. Each application can have their own profile, and there is also a default profile used for applications without one (the default profile is handled differently depending on which version of Linux you are running).

To learn more about PAM and the many options and modules available for it see the following:

PAM and provisioning

PAM recommendations for user provisioning:

If you are using PAM authentication to connect to an external authentication provider, you can use a PAM module like pam_mkhomedir to automatically create the users’ home directories on login.
User provisioning requires PAM sessions to be used is most cases. See the PAM Sessions section for details on how Workbench can be configured to use those.
If you are using SAML, OpenID or Proxied authentication and local system accounts are automatically created by sssd, a PAM configuration with the module pam_rootok must be used, since PAM sessions will be started by Workbench using root in the behalf of the actual user.

PAM authentication

By default, Workbench authenticates users via the Linux standard PAM API. PAM itself is typically configured by default to authenticate against the system user database (/etc/passwd) however it can also be configured to authenticate against a wide variety of other systems including Active Directory, LDAP, and Kerberos.

Users can log-in with username aliases, but will be represented in the system with the primary username for a given user-id.

Note

PAM can be used for both authentication as well as to tailor the environment for users with PAM Sessions. This section only describes PAM for the purposes of authentication.

Default PAM configuration

Debian / Ubuntu

On Debian and Ubuntu systems Workbench does not provide a Workbench specific PAM configuration file. As a result, Workbench uses the /etc/pam.d/other profile, which by default inherits from a set of common configuration files:

/* /etc/pam.d/other */
  @include common-auth
  @include common-account
  @include common-password
  @include common-session

If the /etc/pam.d/other profile reflects the authentication system and policies that you’d like RStudio to use then no further configuration is required. If you want to create a custom PAM profile for RStudio you would create a file named /etc/pam.d/rstudio and specify whatever settings are appropriate.

RedHat / SUSE

On RedHat and SUSE systems applications without their own PAM profiles are denied access by default. Therefore to ensure that RStudio is running and available after installation a default PAM profile is installed at /etc/pam.d/rstudio. This profile is configured to require a user-id greater than 500 and to authenticate users against local system accounts:

; /etc/pam.d/rstudio
auth      requisite      pam_succeed_if.so uid >= 500 quiet
auth      required       pam_unix.so nodelay
account   required       pam_unix.so

Customizing the PAM profile for external identity providers

The default /etc/pam.d/rstudio profile on RedHat and SUSE authenticates against local system accounts only, using the pam_unix module. If your organization uses an external identity provider (such as Active Directory, LDAP, or Kerberos) through modules like pam_sss or pam_ldap, users from those providers cannot log in to Workbench. To resolve this, update the rstudio profile to include the relevant modules.

On Debian and Ubuntu, Workbench uses the default PAM profile at /etc/pam.d/other, which includes the system-wide common-* configuration files. If those files already include your identity provider modules, Workbench authentication works without additional PAM configuration.

To update the rstudio profile, either copy an existing system profile or edit the profile directly.

Copying a system profile

If a system profile such as /etc/pam.d/login already authenticates against your identity provider, copy it over the rstudio profile:

Terminal

sudo cp /etc/pam.d/login /etc/pam.d/rstudio

Review the source profile before copying to confirm it includes the authentication modules you need (e.g., pam_sss.so for System Security Services Daemon (SSSD), pam_ldap.so for LDAP). Not all system profiles include the same modules. Choose the profile that matches the authentication behavior you want for Workbench.

Note

session entries in the copied profile have no effect under /etc/pam.d/rstudio. Workbench consults the rstudio profile only for authentication and account checks. If you need session-level behavior such as pam_mkhomedir or pam_limits, configure it separately. See PAM Sessions for details.

Editing the profile directly

To add specific modules without replacing the entire profile, edit /etc/pam.d/rstudio directly. For example, to add SSSD-based authentication alongside local accounts:

/etc/pam.d/rstudio

auth      requisite      pam_succeed_if.so uid >= 500 quiet
auth      sufficient     pam_sss.so
auth      required       pam_unix.so nodelay
account   sufficient     pam_sss.so
account   required       pam_unix.so

Consult your identity provider documentation for the specific PAM modules and options required.

After updating the rstudio profile, verify authentication with the bundled pamtester utility. If pamtester succeeds with a system profile (such as login) but fails with rstudio, the rstudio profile is missing modules that the system profile includes. Update the rstudio profile using one of the approaches above, then re-test.

Diagnosing PAM authentication problems

If you are unable to log into Workbench there may be an underlying problem with the PAM configuration. The best way to diagnose PAM configuration problems is to use the pamtester utility (which is bundled with Workbench). Using pamtester enables you to test authentication in an isolated environment as well as to see much more detailed diagnostics.

The pamtester utility is located at /usr/lib/rstudio-server/bin/pamtester. To invoke it you pass several arguments indicating the PAM profile to test, the user to test for, and whether you want verbose output. For example:

sudo /usr/lib/rstudio-server/bin/pamtester --verbose rstudio <username> authenticate

You can find more detailed documentation on using pamtester here: http://linux.die.net/man/1/pamtester.

Additionally, Workbench expects the PAM password prompt text when logging in to be Password:. If you use a nonstandard password prompt, you must disable strict prompt matching by modifying /etc/rstudio/rserver.conf like so:

auth-pam-require-password-prompt=0

Keep in mind that PAM session configurations involved in the aforementioned PAM Sessions section for Workbench is not considered when authenticating users from the login page. They only affect the running of sessions from Workbench once the user has already been authenticated. Therefore, if you wish to add constraints to users to prevent access to Workbench, you must do so in the auth configuration instead of the sessions configuration.