This article is based on this section of the administrator's guide.
LDAP and Active Directory
RStudio Connect can integrate with your company’s LDAP or Active Directory (AD) infrastructure. User authentication and user search requests will be directed to the LDAP/AD server.
Several configurations are discussed below, and additional examples are available in the appendix of the administrator's guide.
LDAP and Active Directory support in RStudio Connect has the following constraints:
- Your LDAP/AD user objects must contain a user’s first name, last name, email address, and username.
- Changes to a user (e.g. their name, email address, or username) will not propagate to RStudio Connect once the user is created internally.
- When using single bind, the DN of a user must contain their username (i.e. must utilize the
UsernameAttribute). For example, it is not supported if the DN for a user is
cn=SueJacobs,ou=People,dc=company,dc=combut their actual username is stored in the
SAMAccountNameLDAP attribute. You must use double bind when the DN does not contain the username.
- When using a single-bind configuration, searches will only include users who have previously logged into RStudio Connect.
- When using a single-bind configuration, groups will be unavailable.
- A username or DN containing a forward slash (
/) is not supported.
Defining an LDAP or AD section
RStudio Connect does support the notion of having multiple LDAP or AD servers. This can be utilized by defining multiple LDAP sections.
To define an LDAP or AD section in the configuration file, add a header like the following:
[LDAP "European LDAP Server"] ...
An LDAP/AD configuration section header is always bounded by square brackets (
). After the section type LDAP is the effective name of the LDAP or AD server (
"European LDAP Server" in the example). Make sure that this text is unique per LDAP or AD section you configure. The LDAP section name is treated case sensitively.
RStudio Connect can support more than one LDAP server through multiple, uniquely named LDAP configuration sections. Other complex LDAP configurations can also be achieved by using multiple LDAP sections.
If multiple LDAP sections have the same name, they will be combined as described in this section of the admin guide. As this is unlikely your intent, please take care to give unique names to each LDAP configuration section.
Here is an sample configuration using two LDAP sections.
[LDAP "European LDAP Server"] ... [LDAP "Statistics Department LDAP Server"] ...
Each of these sections will have a variety of configuration settings, which are explained below.
Complete Configuration Example
Here is a complete LDAP configuration as an example. Here, we are communicating with an OpenLDAP server on the local host; see the documentation for
ServerAddress to learn how to direct requests elsewhere. The other settings will probably need adjustment for your environment. Talk to your LDAP administrator if you need help with your organization’s LDAP hierarchy.
[LDAP "Sample OpenLDAP Configuration"] ServerAddress = 127.0.0.1:389 BindDN = "cn=admin,dc=example-openldap" BindPassword = "XXXXXXXX" UserSearchBaseDN = "ou=People,dc=example-openldap" UsernameAttribute = "uid" UserObjectClass = "posixAccount" UserEmailAttribute = mail UserFirstNameAttribute = givenName UserLastNameAttribute = sn
This sample configuration assumed a very simple OpenLDAP structure; here is a sample user record to show the mapping between LDAP records and RStudio Connect LDAP configuration.
dn: uid=john,ou=People,dc=example-openldap objectClass: inetOrgPerson objectClass: posixAccount objectClass: shadowAccount uid: john sn: Doe givenName: John cn: John Doe displayName: John Doe uidNumber: 10000 gidNumber: 5000 userPassword: johnldap gecos: John Doe loginShell: /bin/bash homeDirectory: /home/john mail: firstname.lastname@example.org
More LDAP configuration scenarios can be found in this section of the admin guide.
LDAP or AD Configuration Settings
ServerAddress (required) is used to define the location of the LDAP/AD server. This should contain an IP address or DNS address, and a port (colon separated). Most LDAP/AD servers operate on port
636 (for SSL). But you can specify any port that fits your environment.
ServerAddress = 127.0.0.1:389 ServerAddress = ldap.company.com:389 ServerAddress = ldaps.company.com:636 ServerAddress = private.internal.local:7554
TLS is a Boolean (true/false) attribute that causes all connections to your LDAP/AD server to use TLS (SSL). The default value for this is
false. This cannot be enabled if
TLS = true TLS = false
StartTLS is a Boolean (true/false) attribute that causes connections to your LDAP/AD server to initially use an unencrypted channel but then upgrade to a TLS connection using “Opportunistic TLS”. The default value for this is
false. This cannot be enabled if
StartTLS = true StartTLS = false
At present, the error messages associated with StartTLS problems can be cryptic. If you’re encountering issues while configuring StartTLS, consider adding debug logging for LDAP by including the following line in your configuration file.
[Debug] Log = ldap
TLSCACertificate is a file location that is a certificate authority that is used to connect to an LDAP server securely. This file should be in PEM format.
ServerTLSInsecure is a Boolean (true/false) attribute that allows insecure TLS connections. This controls whether a client will verify the server’s certificate chain and host name. If this is
true, RStudio Connect will accept any certificate presented by the server and any host name in that certificate. Setting to
true is susceptible to main-in-the-middle attacks, but is required if, for example, your server uses a self-signed certificate. The default value is
ServerTLSInsecure = true ServerTLSInsecure = false
BindPassword are credentials used to connect to an LDAP/AD server to authenticate, search for users, and other functionality. While it is encouraged to specify these two attributes (aka double bind), it is not required (aka single bind). These credentials should have read-only administrator’s rights, if configured.
If you do not specify these attributes, some functionality of RStudio Connect will not work. For example, searching for users to add as collaborators, or sending email documents will only work partially.
# Example DN BindDN = uid=john,ou=People,dc=company,dc=com BindPassword = johnpassword # Example UPN BindDN = email@example.com BindPassword = adminpassword # Example NT-style login BindDN = COMPANY\\admin # we use double slashes (\\) to character escape the last slash BindPassword = adminpassword
UserSearchBaseDN (required) is the starting point from which RStudio Connect will search for user entries in your LDAP/AD server.
UserSearchBaseDN = dc=company,dc=com UserSearchBaseDN = ou=People,dc=company,dc=com
UserObjectClass (required) is the
objectClass that a user in your LDAP/AD structure will have. Common examples of this are
UserObjectClass = user UserObjectClass = posixAccount
UsernameAttribute (required) is the LDAP entry attribute that contains the username of a user.
UsernameAttribute = uid UsernameAttribute = sAMAccountName
UserFirstNameAttribute (required) is the LDAP entry attribute that contains the first name of a user.
UserFirstNameAttribute = givenName
UserLastNameAttribute (required) is the LDAP entry attribute that contains the last name of a user.
UserLastNameAttribute = sn
UserEmailAttribute (required) is the LDAP entry attribute that contains the email address of a user.
UserEmailAttribute = mail
WhitelistedLoginGroup defines a group DN that a user must be a member of in order to login into Connect. You can specify this attribute multiple times. Be aware that this feature restricts only the ability for users to login. Users not in this group could still be referenced when setting access controls for content or as email recipients. Because the users could not login, they would not be able to access content even if they were added as a viewer or collaborator, but they might still be able to receive emailed versions of reports.
WhitelistedLoginGroup = cn=admins,ou=group,dc=company,dc=com WhitelistedLoginGroup = cn=scientists,ou=group,dc=company,dc=com
GroupUserObjectClass is the
objectClass that a group in your LDAP/AD structure will have. Common examples of this are
GroupObjectClass = group GroupObjectClass = posixGroup
GroupNameAttribute is the LDAP entry attribute that contains the name of a group.
GroupNameAttribute = cn GroupNameAttribute = sAMAccountName
GroupSearchBaseDN is the starting point from which RStudio Connect will search for group entries in your LDAP/AD server.
GroupSearchBaseDN = dc=company,dc=com GroupSearchBaseDN = ou=Groups,dc=company,dc=com