LDAP and Active Directory authentication in RStudio Connect

Avatar
Amanda Gadrow
Follow

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 except when the user logs in to RStudio Connect after those changes.
  • When using single bind, the DN of a user must contain their username (i.e. must utilize the UsernameAttribute). Using a different attribute for username such as CN only to match the DN may cause users to have to type their full name to login.  For example, it is not supported if the DN for a user is cn=SueJacobs,ou=People,dc=company,dc=com but their actual username is stored in the uid or SAMAccountName LDAP 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.

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.

Note: LDAP usernames are unique in RStudio Connect. It means that when two users share the same username only the first one logging in to RStudio Connect will be able to obtain an account. Others will be refused as a duplicate. This applies especially when there are multiple LDAP sections.

Complete OpenLDAP Configuration Example

Here is a complete OpenLDAP 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"
UniqueIDAttribute = "entryUUID"
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: john@example.com
entryUUID: c1afa3d6-d688-1037-99f0-d7682e3458da

More LDAP configuration scenarios can be found in this section of the admin guide.

Complete AD Configuration Example

Here is a complete AD configuration as an example. Here, we are communicating with an AD 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 = "example-ad\\admin"
BindPassword = "XXXXXXXX"
UserSearchBaseDN = "cn=Users,dc=example-ad"
UsernameAttribute = "sAMAccountName"
UserObjectClass = "user"
UserEmailAttribute = mail
UserFirstNameAttribute = givenName
UserLastNameAttribute = sn
UniqueIDAttribute = objectGUID

This sample configuration assumed a standard simple AD structure; here is a sample user record to show the mapping between LDAP records and RStudio Connect LDAP configuration.

dn: CN=John Doe,CN=Users,DC=example-ad
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: user
cn: John Doe
sn: Doe
givenName: John
distinguishedName: CN=John Doe,CN=Users,DC=example-ad
displayName: John Doe
name: John Doe
objectGUID:: leleB493l05mJvcu5flSRQ==
objectSid:: AQUAAAAAAAUVAAAAvtYm4NX9spNPtO6VVwQAAA==
sAMAccountName: john
userPrincipalName: john@example-ad
mail: john@example-ad

LDAP or AD Configuration Settings

ServerAddress

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 389or 636 (for SSL). But you can specify any port that fits your environment.

Examples

ServerAddress = 127.0.0.1:389
ServerAddress = ldap.company.com:389
ServerAddress = ldaps.company.com:636
ServerAddress = private.internal.local:7554

TLS

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 StartTLS is true.

Examples

TLS = true
TLS = false

StartTLS

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 TLS is true.

Examples

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 the LDAP section of your configuration file.

Logging = true

TLSCACertificate

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.

Examples

TLSCACertificate= /etc/ssl/cert/ca.pem

ServerTLSInsecure

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 false.

Examples

ServerTLSInsecure = true
ServerTLSInsecure = false

BindDN and BindPassword

BindDN and 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.

The BindDN can be a DN, UPN, or NT-style login.

Examples

# Example DN
BindDN = uid=john,ou=People,dc=company,dc=com
BindPassword = johnpassword

# Example UPN
BindDN = admin@company.com
BindPassword = adminpassword

# Example NT-style login
BindDN = "COMPANY\\admin"  # we use double slashes (\\) to character escape the last slash
BindPassword = "adminpassword"

UserSearchBaseDN

UserSearchBaseDN (required) is the starting point from which RStudio Connect will search for user entries in your LDAP/AD server.

Examples

UserSearchBaseDN = dc=company,dc=com
UserSearchBaseDN = ou=People,dc=company,dc=com

UserObjectClass

UserObjectClass (required) is the objectClass that a user in your LDAP/AD structure will have. Common examples of this are user, posixAccount, organizationalPerson, person, and inetOrgPerson.

Examples

UserObjectClass = user
UserObjectClass = posixAccount

UniqueIDAttribute

UniqueIDAttribute (optional) is the LDAP entry attribute that contains the username the user's unique identifier. Without this setting the user will be identified by the DN which may change over time (when the user's legal name changes), leading to RStudio Connect treat it as a duplicate user.

Examples

UniqueIDAttribute = entryUUID # OpenLDAP
UniqueIDAttribute = objectGUID # AD

UsernameAttribute

UsernameAttribute (required) is the LDAP entry attribute that contains the username of a user.

Examples

UsernameAttribute = uid
UsernameAttribute = sAMAccountName

UserFirstNameAttribute

UserFirstNameAttribute (required) is the LDAP entry attribute that contains the first name of a user.

Examples

UserFirstNameAttribute = givenName

UserLastNameAttribute

UserLastNameAttribute (required) is the LDAP entry attribute that contains the last name of a user.

Examples

UserLastNameAttribute = sn

UserEmailAttribute

UserEmailAttribute (required) is the LDAP entry attribute that contains the email address of a user.

Examples

UserEmailAttribute = mail

PermittedLoginGroup

PermittedLoginGroup 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.

Note:PermittedLoginGroup replaces the deprecated WhitelistedLoginGroup 

Examples

PermittedLoginGroup = cn=admins,ou=group,dc=company,dc=com
PermittedLoginGroup = cn=scientists,ou=group,dc=company,dc=com

GroupObjectClass

GroupUserObjectClass is the objectClass that a group in your LDAP/AD structure will have. Common examples of this are group, and posixGroup.

Examples

GroupObjectClass = group
GroupObjectClass = posixGroup

GroupUniqueIDAttribute

GroupUniqueIDAttribute (optional) is the LDAP entry attribute that contains the username the group's unique identifier. Without this setting the group will be identified by the DN which may change over time (when a department name changes within the company), leading to RStudio Connect to treat it as a duplicate group.

Examples

GroupUniqueIDAttribute = entryUUID # OpenLDAP
GroupUniqueIDAttribute = objectGUID # AD

GroupNameAttribute

GroupNameAttribute is the LDAP entry attribute that contains the name of a group.

Examples

GroupNameAttribute = cn
GroupNameAttribute = sAMAccountName

GroupSearchBaseDN

GroupSearchBaseDN is the starting point from which RStudio Connect will search for group entries in your LDAP/AD server.

Examples

GroupSearchBaseDN = dc=company,dc=com
GroupSearchBaseDN = ou=Groups,dc=company,dc=com

Comments