Shiny Server Pro: LDAP Authentication Examples

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

This article will focus on specific examples of setting up LDAP with Shiny Server Pro.  For more information, please see the full article on LDAP and Active Directory configuration here.

Introduction

A holistic overview of LDAP is outside of the scope of this document, so if you lack a solid background in LDAP, you would benefit from consulting with a system administrator in your organization to configure these settings. 

We strongly recommend that before you start configuring for LDAP, first enable TRACE logging on the server. For instructions on how to modify logging level refer to this section of the Shiny Server Administrator's Guide. 

Finally, we currently support only a limited subset of Unicode characters as usernames for LDAP. Usernames must include only:

Alphanumeric characters

_   Underscore

.    Period

@  "at" symbol

We do not permit empty usernames or passwords.

Examples

Several examples are presented in this article, along with the full list of configuration options for the auth_ldap directive:

LDAP with groups

LDAP with double bind

Full list of auth_ldap configuration options

LDAP with groups

The parent directive for all LDAP-related settings is auth_ldap, which accepts an LDAP URL as its first argument. All other child settings within this directive are not required, but may be needed depending on your LDAP configuration.  To set up groups, it may be helpful to see an example.

Given the following: 

LDAP server host: ldap://ldap.example.org

Root DIT of the directory to use: dc=example,dc=org

Query for user's group membership: memberUid={username}

Subtree in which groups are stored: ou=Groups

The directive in Shiny Server Pro should be:

auth_ldap ldap://ldap.example.org/dc=example,dc=org {
   group_filter "memberUid={username}";
   group_search_base ou=Groups;
 }

Details:

group_filter defines the LDAP query to use in determining a user's group membership. The query should return all groups of which the given user is a member.  The default for auth_ldap is uniqueMember={username}, which checks the uniqueMembers setting from the groupOfUniqueMembers LDAP class. If you're using the posixGroup LDAP class to store your group memberships, you will likely need to set this value to memberUid={username}.

If you find that the number of groups returned when you log in is very high, you should consider adding a second filter to reduce the number of groups returned for users.  You can do this with an & clause, e.g.,

group_filter "&(cn=*Shiny*)(memberUid={username})";

This configuration would query for the memberUid and any groups that have the word “Shiny” in them (the asterisks are wildcards).

group_search_base defines the subtree in which groups are stored, and will be used as the root of all LDAP queries which attempt to find the groups of which a user is a member.  The default value for auth_ldap is ou=Groups, and if configured to use an empty string as the base, then the unmodified root DIT will be used as the group search base.

Once this is set up properly, you can then add a 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 app1Users admins;
}

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

LDAP with double bind

Shiny Server Pro uses single-bind LDAP authentication by default for username and password validation. To use double-bind LDAP authentication, set the base_bind directive to specify a user DN and password for the initial LDAP bind operation, and the user_filter directive to specify a search filter for the DN associated with the user attempting login.

Given the following:

LDAP server host: ldap://ldap.example.org

Root DIT of the directory to use: dc=example,dc=org

User DN: uid=searcher,ou=People,{root}

Password or path to password file: password-for-searcher

Filter to find the user object that matches the username: uid={username}

The directive in Shiny Server Pro should be:

auth_ldap ldap://ldap.example.org/dc=example,dc=org {
  base_bind "uid=searcher,ou=People,{root}" "password-for-searcher";
  user_filter "uid={username}";
}

Details:

In this example, an account called searcher is used to perform the initial bind operation.

The {root} variable is populated with the root DIT provided to the parent auth_ldap setting.

Note that user_filter is required when base_bind is in use.

If you do not wish to include a plain-text password in the base_bind definition, you could choose to include the path to a password file instead:

auth_ldap ldap://ldap.example.org/dc=example,dc=org {
  base_bind "uid=searcher,ou=People,{root}" "/etc/shiny-server/ldap-base-bind-password.txt";
  user_filter "uid={username}";
}

In this case, Shiny Server Pro reads the LDAP password from the file /etc/shiny-server/ldap-base-bind-password.txt. Shiny Server Pro will retain root privileges when using a file to contain the LDAP password. This allows you to tighten the permissions around the file containing the LDAP password to only allow the root user to read it.

Configuration options for auth_ldap

The parent directive for all LDAP-related settings is auth_ldap, which accepts an LDAP URL as its first argument. All other child settings within this directive are not required, but may be needed depending on your LDAP configuration. 

For additional information, please see the LDAP / Active Directory section of the admin guide.