Support

Shiny Server Pro: Active Directory Authentication Examples

Follow

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

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

Explicit SSL certificate: /etc/ssl/certs/example-org.cert

 

The directive in Shiny Server Pro should be:

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

 

Details:

trusted_ca defines the SSL certificate to use to reach the LDAP server.  By default, Shiny Server Pro trusts many standard SSL Certificate Authorities (CAs). If your organization uses a non-trusted CA to sign its SSL certificates, you will need to explicitly tell Shiny Server Pro to trust this CA's certificate. You can do this by placing the CA's certificate (in PEM format) in a file on your machine and pointing this setting to that file. You can add multiple trusted CAs (space-delimited) if you desire. If this value is provided, the standard list of trusted CAs will be overridden with the provided certificate.

Alternately, you could set the check_ssl_ca directive to false to disable the checking of CAs entirely.

 

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.

Directive

Description

auth_active_dir default

check_ssl_ca

When using LDAP over SSL, whether to check that the SSL certificate on the LDAP server was signed by a trusted Certificate Authority

true

trusted_ca

When using LDAP over SSL, path to a certificate issued by a non-trusted Certificate Authority

none

user_bind_template

Manipulate the given username into the username used to perform the LDAP bind operation

{username}@example.org, where "example.org" is the domain name you provided as the second argument to auth_active_dir

user_search_base

The subtree in which users are stored

cn=Users

user_filter

LDAP filter used to find the user object which matches the entered username

userPrincipalName={userBind}

group_name_attribute

The attribute of the LDAP group object in which the group name is stored

cn

group_search_base

The subtree in which groups are stored

cn=Users

group_filter

The LDAP query to use in determining a user's group membership

member:1.2.840.113556.1.4.1941:={userDN}

 

Comments