Shiny Server Pro: PAM Authentication Examples

This article is adapted from the Shiny Server Administrator's Guide for version 1.4.2.

For additional information, please also see the Setting up PAM with Shiny Server Pro article.

Overview

Shiny Server Professional can authenticate users via the Linux standard PAM (Pluggable Authentication Module) API. PAM 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 and LDAP.

This section describes the PAM configuration used for authentication. Note that PAM can be used for both authentication as well as to tailor the environment for user sessions (PAM sessions). This article describes only authentication; see the PAM Sessions section of the admin guide for details on how Shiny Server can be configured to use PAM sessions.

Topics in this article:

PAM Basics

Default PAM Configuration

PAM and Kerberos

PAM with groups

Debugging your PAM configuration

PAM Basics

PAM profiles are located in the /etc/pam.d directory. Each application can have its 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:

• http://en.wikipedia.org/wiki/Pluggable_authentication_module
• http://www.centos.org/docs/5/html/Deployment_Guide-en-US/ch-pam.html
• http://tldp.org/HOWTO/User-Authentication-HOWTO/x115.html
• http://linux.die.net/man/8/pam

Default PAM Configuration

Debian/Ubuntu

On Debian and Ubuntu systems Shiny Server does not provide a Shiny-Server-specific PAM configuration file. As a result, Shiny Server 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 Shiny Server to use then no further configuration is required. If you want to create a custom PAM profile for Shiny Server you would create a file named /etc/pam.d/shiny-server and specify whatever settings are appropriate.

RedHat/CentOS/SLES

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

/etc/pam.d/shiny-server

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 Shiny Server. 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 Shiny Server one. For example:

$ sudo cp /etc/pam.d/login /etc/pam.d/shiny-server

PAM and Kerberos

Shiny Server Professional supports integration with Kerberos for seamless authentication to other applications via Kerberos tickets. To enable this feature, add the following to the top level of your /etc/shiny-server/shiny-server.conf file:

run_as :AUTH_USER:;
auth_pam true;
pam_sessions_profile shiny-session;

This specifies that you are using a file named shiny-session for the pam.d session profile, but the name could be anything as long as it matches your actual filename.

You also need to customize your Shiny Server pam.d files: shiny-server and shiny-session. This simple example uses pam_krb5.so as a guide.

/etc/pam.d/shiny-server

auth       sufficient     pam_krb5.so 
account    required       pam_krb5.so 
session    requisite      pam_krb5.so 

/etc/pam.d/shiny-session

auth        required      pam_krb5.so 
account     [default=bad success=ok user_unknown=ignore] pam_krb5.so 
password    sufficient    pam_krb5.so use_authtok 
session     requisite     pam_krb5.so 

Note that Kerberos is not supported for LDAP implementations.

PAM with Groups

Once your PAM authentication is working, you can then add a required_user or required_group directive to your location definitions, to restrict access to particular applications if you like.  For example:

location /app1 {
  site_dir /srv/shiny-server/app1;
  required_group group1 admins;
}

With this configuration, the /app1 application is only accessible to members of the group1 and admins PAM groups. 

Debugging your PAM configuration

If something is not working with your PAM configuration, there are a few things you can do to investigate the problem.

1. Ensure that the users can log in to the server via another service, e.g., SSH or interactively to the GUI, if that is available.  If they are able to log in elsewhere but not into Shiny Server, you may want to copy over the working PAM profile, e.g.,
       sudo cp /etc/pam.d/login /etc/pam.d/shiny-server
2. Verify that you have set the correct location in the shiny-server.conf file, and the URL you are using is valid.
3. Verify that you have restarted the Shiny Server process after making configuration changes.
4. Review the resources listed at the bottom of the Setting up PAM with Shiny Server Pro article.