PAM Authentication

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:

• https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/system-level_authentication_guide/pluggable_authentication_modules
• http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html
• http://linux.die.net/man/8/pam

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 / CentOS / SUSE

On RedHat, CentOS 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

This default PAM profile may not reflect the authentication behavior that you want for Workbench. In that case, some customization may be required. If you’ve already set up another PAM profile (e.g. /etc/pam.d/login) with the desired behavior then it may be enough to simply copy that profile over the Workbench one. For example:

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

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.