Shiny Server Pro: Active Directory 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 Active Directory with Shiny Server Pro.  For more information, please see the full article on LDAP and Active Directory configuration here.

Introduction

A holistic overview of Active Directory is outside of the scope of this document, so if you lack a solid background in LDAP and Active Directory, 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 Active Directory, 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_active_dir directive:

Active Directory with untrusted CA

Active Directory with groups

Full list of auth_active_dir configuration options

Active Directory with Untrusted Certificate Authority on LDAP Server

auth_active_dir ldaps://dc01.example.org/dc=example,dc=org example.org {
   trusted_ca /etc/ssl/certs/example-org.cert;
 }

Active Directory with Groups

The parent directive for all AD-related settings is auth_active_dir, which accepts an LDAP URL as its first argument, and the suffix (typically a domain name) to be added to all usernames when attempting to bind, as its second 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: ldaps://dc01.example.org

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

Bind suffix for users: example.org

Pattern to transform the given username for binding: {username}@example.org

Filter to look up the user's DN given their username: sAMAccountName={username}

Query for user's group membership: member={userDN}

Subtree in which groups are stored: ou=Example

The directive in Shiny Server Pro should be:

auth_active_dir ldaps://dc01.example.org/dc=example,dc=org example.org {
 user_bind_template “{username}@example.org”;
 user_filter “sAMAccountName={username}”;
 user_search_base “ou=Users”;
 group_filter “member={userDN}”;
 group_search_base ou=Example;
}

Details:

user_bind_template is used to manipulate the given username into the username used to perform the LDAP bind operation. The default value is {username}@example.org, where "example.org" is the domain name you provided as the second argument to auth_active_dir.

user_filter stores the LDAP filter used to find the user object which matches the entered username. Many Active Directory implementations do not use the username as a part of the user's DN, so this setting is used to perform an extra LDAP query after binding to determine the user's DN based on their username before group membership can be determined. The default value for auth_active_dir is userPrincipalName={userBind}.

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_active_dir is member:1.2.840.113556.1.4.1941:={userDN}.

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*)(member:1.2.840.113556.1.4.1941:={userDN})";

This configuration would query for the member 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_active_dir is cn=Users, 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 Active Directory groups.

Configuration Options for auth_active_dir

The parent directive for all AD-related settings is auth_active_dir, which accepts an LDAP URL as its first argument, and the suffix (typically a domain name) to be added to all usernames when attempting to bind, as its second 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.