Advanced LDAP and Active Directory Configuration#

The information provided here aims to guide RStudio Connect administrators to integrate with more complex LDAP or Active Directory (AD) environments, solve performance issues or explore rarely used functionality supported by the RStudio Connect LDAP provider.

In this appendix:

Integrating with Multiple LDAP/AD Servers
LDAP/AD Settings by Category
Performance Considerations

Note

This section is focused on the commonly used settings. For a complete list of all LDAP settings, please see the LDAP section in the Configuration appendix.

Integrating with Multiple LDAP/AD Servers#

Start an LDAP or Active Directory configuration with a LDAP section header like the following:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "European AD Server"]
...

An LDAP or Active Directory configuration section header is always of the form [LDAP "EFFECTIVE NAME"]. The "effective name" is a name that is meaningful to your organization ("European AD Server" in the example).

The configuration settings in each LDAP section are explained in more detail below in LDAP/AD Settings by Category.

Adding Multiple Configuration Sections#

RStudio Connect supports more than one LDAP/AD server through multiple, uniquely named LDAP configuration sections. Other complex LDAP/AD configurations can also be achieved by using multiple LDAP sections.

Multiple sections should be used for the following scenarios:

Users from multiple domains (or forests) will be using RStudio Connect. A single section pointing to the Global Catalog is an alternative for this scenario when using Active Directory.
Users from multiple geographic regions or organization will be using RStudio Connect and there is not a common LDAP domain.
Two or more LDAP servers work in contingency to each other for achieving high availability.

Note

Make sure each LDAP configuration section has a unique effective name. If multiple LDAP sections have the same name, they will be combined as described in the Configuration appendix. The LDAP section name is treated case sensitively.

Important

Except for the Connectivity Settings, all other settings must be the same across all LDAP sections. RStudio Connect does not support working with different LDAP vendors or using different setups in each section.

Here is a sample configuration using two LDAP sections.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "European LDAP Server"]
...

[LDAP "Statistics Department LDAP Server"]
...

LDAP/AD Settings by Category#

The LDAP/AD settings operate in concert and can be organized in categories for a better understanding of the capabilities provided by RStudio Connect:

Connectivity Settings
User Settings
Group Settings

Connectivity Settings#

These settings determine how RStudio Connect connects to LDAP.

`ServerAddress`#

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
ServerAddress = 127.0.0.1:389
ServerAddress = ldap.company.com:389
ServerAddress = ldaps.company.com:636
ServerAddress = private.internal.local:7554

`TLS`#

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

Note

This setting implies the use of the legacy "ldaps" protocol (LDAP + SSL) which in general is served on the port 636.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
TLS = true
TLS = false

`StartTLS`#

LDAP.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 the StartTLS LDAP extension. The default value for this is false. This cannot be enabled if TLS is true.

Note

This setting must not be used with the legacy "ldaps" protocol. In general, a connection upgrade to use the TLS encryption can be attempted in the standard LDAP port 389.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
Logging = true

`TLSCACertificate`#

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.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
TLSCACertificate= /etc/ssl/cert/ca.pem

Note

If either LDAP.TLS or LDAP.StartTLS are enabled, without a certificate the connection will fail unless LDAP.ServerTLSInsecure is enabled.

`ServerTLSInsecure`#

LDAP.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 man-in-the-middle attacks, but is required if, for example, your server uses a self-signed certificate. The default value is false.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
ServerTLSInsecure = true
ServerTLSInsecure = false

`BindDN` and `BindPassword`#

LDAP.BindDN and LDAP.BindPassword are credentials used to connect to an LDAP/AD server to authenticate, search for users, and other functionality. While it is recommended to specify these two attributes, it is not required. Without these credentials the use of LDAP is mostly limited to user authentication and LDAP group support cannot be used. These credentials should have read-only administrator's rights, if configured.

Tip

The BindPassword value and BindPasswordFile contents can be encrypted to avoid credential leakage. See the Property Types configuration appendix for details.

If you do not specify these attributes, some functionality of RStudio Connect will not work. For example, searching for remote users within the Add User dialog on the People tab, or sending email documents will only work partially.

The BindDN is generally a DN, but it can be a UPN, or NT-style login for Active Directory.

Tip

Quote BindDN and BindPassword values. Escape literal double-quote (") and backslash (\) characters.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
; Example DN
BindDN = "uid=john,ou=People,dc=company,dc=com"
BindPassword = "johnpassword"

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
; Example UPN
BindDN = "admin@company.com"
BindPassword = "adminpassword"

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
; Example NT-style login
; Double-slashes (\\) escape the backslash.
BindDN = "COMPANY\\admin"
BindPassword = "adminpassword"

`AnonymousBind`#

LDAP.AnonymousBind instructs RStudio Connect to establish an anonymous bind to your LDAP/AD server. For organizations that support anonymous binds, you may use this option instead of LDAP.BindDN and LDAP.BindPassword.

For this to work properly, your LDAP server must allow anonymous binds to search and view all pertinent groups, group memberships, and users.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
AnonymousBind = true

User Settings#

These settings determine which object in LDAP is considered a user, where they are located in the LDAP tree and which attributes RStudio Connect should use.

`UserSearchBaseDN`#

LDAP.UserSearchBaseDN (required) is the starting point from which RStudio Connect will search for user entries in your LDAP/AD server. The "deeper" this location is in your LDAP server, the faster RStudio Connect will be able to query LDAP due to the reduced number of visible users.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserSearchBaseDN = dc=company,dc=com
UserSearchBaseDN = ou=People,dc=company,dc=com

`UserObjectClass`#

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

UserObjectClass is used to define LDAP.UserFilterBase if that property is not explicitly configured. Either UserObjectClass or UserFilterBase must be defined. If both have values, only UserFilterBase will be used.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserObjectClass = user
UserObjectClass = posixAccount

`UserFilterBase`#

The LDAP.UserFilterBase attribute allows more flexibility when searching for user objects in complicated LDAP hierarchies. It uses the LDAP query syntax and it is combined with other queries in RStudio Connect.

Either LDAP.UserObjectClass or UserFilterBase must be defined. If UserFilterBase is unset, it is given a default value of objectClass={UserObjectClass}.

Important

The custom LDAP query in UserFilterBase generally must be crafted to also include the group's objectClass that would otherwise be defined by UserObjectClass.

If users are identified by two separate objectClass values, you might use the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserFilterBase = &(objectClass=user)(objectClass=statistician)

You can disqualify an objectClass value with the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserFilterBase = &(objectClass=user)(!(objectClass=computer))

`UniqueIdAttribute`#

UniqueIdAttribute (optional, default "DN") is the vendor-specific object attribute present for all users which has a unique value that identities the object persistently. Commonly used attributes include:

objectGUID (Microsoft AD)
entryUUID (OpenLDAP)
orclGuid (Oracle OID)
ibm-entryUUID (IBM RACF)
GUID (Novell eDirectory)
nsUniqueID (389 Directory Server)

Please refer to your LDAP vendor documentation for the correct value.

The default value of DN is stored in RStudio Connect in plain text. However, any other attribute will be stored encoded as Base64 since some LDAP vendors (i.e. Microsoft) send binary values for user identities.

WARNING: any change to this setting automatically invalidate all existing users. RStudio Connect will try to detect this, and it will not start if problems are found. Before starting up RStudio Connect with the new configuration, all users must be adjusted to use the updated attribute value via the usermanager CLI, described in the User Management CLI appendix.

Note

The use of the default value of "DN" is not recommended and existing installations should use a different value if possible. RStudio Connect will issue a warning on startup if this condition is detected. The Distinguished Name (DN) is not a persistent value in LDAP/AD and it may change in certain situations. RStudio Connect will no longer be able to refer to a user once their DN changes. You can repair an affected user by updating the DN via the usermanager CLI, described in the User Management CLI appendix.

`UsernameAttribute`#

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

Note

The usernames returned by LDAP or Active Directory are not required to be unique. However, this is only supported when the equal usernames are coming from separate LDAP or Active Directory connections in RStudio Connect. When the same username is being returned in a single LDAP connection (for example in an Active Directory global catalog configuration) then the username must be unique. That may require usernames to use a different LDAP attribute that contains the domain information to distinguish each user.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UsernameAttribute = uid
UsernameAttribute = sAMAccountName

`UserFirstNameAttribute`#

LDAP.UserFirstNameAttribute is the LDAP entry attribute that contains the first name of a user. If your LDAP does not provide this information you can leave it empty. If the setting UserLastNameAttribute is also left empty then first and last names will be editable in RStudio Connect according to the setting Authorization.UserInfoEditableBy.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserFirstNameAttribute = givenName

`UserLastNameAttribute`#

LDAP.UserLastNameAttribute is the LDAP entry attribute that contains the last name of a user. If your LDAP does not provide this information you can leave it empty. If the setting UserFirstNameAttribute is also left empty then first and last names will be editable in RStudio Connect according to the setting Authorization.UserInfoEditableBy.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserLastNameAttribute = sn

`UserEmailAttribute`#

LDAP.UserEmailAttribute is the LDAP entry attribute that contains the email address of a user. If your LDAP does not provide this information you can leave it empty. Email addresses will then be editable in RStudio Connect according to the setting Authorization.UserInfoEditableBy.

Note

Email features will not be available for the user until an email address is entered in the user profile.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserEmailAttribute = mail

`UserRoleAttribute`#

LDAP.UserRoleAttribute is the LDAP entry attribute that contains the user role in RStudio Connect. In the simplest configuration, the option refers to an attribute containing the values viewer, publisher or administrator. However, Authorization.UserRoleMapping can be used to map these roles to other values used by your organization, and returned in an LDAP attribute.

Roles are no longer editable via Dashboard if assigned automatically.

Note

Invalid role values are defaulted to the value of Authorization.DefaultUserRole and the issue is reported in the logs if debug logging is enabled.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
UserRoleAttribute = employeeType

Important

The LDAP.UserRoleAttribute is ignored if roles are assigned based on groups, as determined by Authorization.UserRoleGroupMapping.

Group Settings#

These settings determine which object in LDAP is considered a group, where they are located in the LDAP tree and which attributes RStudio Connect should use.

`GroupSearchBaseDN`#

LDAP.GroupSearchBaseDN is the starting point from which RStudio Connect will search for group entries in your LDAP/AD server. The "deeper" this location is in your LDAP server, the faster RStudio Connect will be able to query LDAP due to reduce number of visible groups.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupSearchBaseDN = dc=company,dc=com
GroupSearchBaseDN = ou=Groups,dc=company,dc=com

`GroupObjectClass`#

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

GroupObjectClass is used to define LDAP.GroupFilterBase if that property is not explicitly configured. Either GroupObjectClass or GroupFilterBase may be defined. If both have values, only GroupFilterBase will be used.

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupObjectClass = group
GroupObjectClass = posixGroup

`GroupFilterBase`#

The LDAP.GroupFilterBase attribute allows more flexibility when searching for group objects in complicated LDAP hierarchies. It uses the LDAP query syntax and it is combined with other queries in RStudio Connect.

Either LDAP.GroupObjectClass or GroupFilterBase may be defined. If GroupFilterBase is unset, it is given a default value of objectClass={GroupObjectClass}.

Important

The custom LDAP query in GroupFilterBase generally must be crafted to also include the group's objectClass that would otherwise be defined by GroupObjectClass.

If groups are identified by two separate objectClass values, you might use the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupFilterBase = &(objectClass=group)(objectClass=club)

You can disqualify an objectClass value with the configuration:

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupFilterBase = &(objectClass=group)(!(objectClass=flock))

`GroupUniqueIdAttribute`#

LDAP.GroupUniqueIdAttribute (optional, default "DN") is the vendor-specific object attribute present for all groups which has a unique value that identities the object persistently. Please refer to your LDAP vendor documentation for the correct value. In general, users and groups use the same value. See UniqueIdAttribute.

WARNING: any change to this setting automatically invalidate all existing groups. RStudio Connect will try to detect this and it will not start if problems are found. Before starting up RStudio Connect with the new configuration, all groups must be adjusted to use the updated attribute value via the usermanager CLI, described in the User Management CLI appendix.

Note

The use of the default value of "DN" is not recommended and existing installations should use a different value if possible. RStudio Connect will issue a warning on startup if this condition is detected. The Distinguished Name (DN) is not a persistent value in LDAP/AD and it may change in certain situations. RStudio Connect will no longer be able to refer to a group once their DN changes. You can repair an affected groups by updating the DN via the usermanager CLI, described in the User Management CLI appendix.

`GroupNameAttribute`#

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
GroupNameAttribute = cn
GroupNameAttribute = sAMAccountName

`PermittedLoginGroup`#

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

Examples

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
PermittedLoginGroup = cn=admins,ou=group,dc=company,dc=com
PermittedLoginGroup = cn=scientists,ou=group,dc=company,dc=com

Performance Considerations#

LDAP performance is directly related to the amount of objects (users or groups) returned by each search operation executed by RStudio Connect.

There are two ways in which one can tweak LDAP settings in RStudio Connect to improve the overall LDAP performance:

Define how much of the LDAP "tree" is visible to RStudio Connect with a deeper search base. Is there a single particular location within LDAP under where RStudio Connect users and groups are organized?
Define how many objects are visible to RStudio Connect with a more specific base filter. Is there any defining characteristics of RStudio Connect users and groups that differentiate them like a name pattern or attribute value?

Note

Additionally, it is possible to disable, temporarily and as a last resort, the automatic group membership lookup RStudio Connect does during user authentication.

Search Base DN (users and groups)#

LDAP has a hierarchical structure forming a "tree". In simple configurations Connect is generally pointing to the "root" of the LDAP tree with the settings UserSearchBaseDN and GroupSearchBaseDN.

For example, GroupSearchBaseDN = dc=company,dc=com points is the "root" of the LDAP (or its own domain) while GroupSearchBaseDN = ou=Groups,dc=company,dc=com points to a "branch" of tree.

The deeper the "branch" is in the LDAP hierarchy, smaller is the number of objects visible to RStudio Connect and faster the searches tend to be.

Tip

As a rule of thumb, RStudio Connect should point to the deepest "branch" in LDAP that contains all objects (users or groups) that are fundamental for its operation.

For example, the location that contain the data science team:

UserSearchBaseDN = ou=DataScience,ou=Research,ou=Users,dc=company,dc=com`
GroupSearchBaseDN = ou=DataScience,ou=Research,ou=Groups,dc=company,dc=com`

If necessary, please consult with your LDAP or Active Directory administrator to obtain the DN location that best balances between performance and functionality.

Object Class and Base Filters (users and groups)#

In simple configurations, instructing RStudio Connect to look for objects of a certain "class" with UserObjectClass and GroupObjectClass is sufficient to determine what objects are the users and groups in LDAP. However, these will match all users and groups, whether or not they are relevant for RStudio Connect operation.

One can be more precise about which users and groups are considered by Connect using "base filters". Base filters configured with UserFilterBase and GroupFilterBase are partial LDAP query conditions appended to all searches executed by RStudio Connect.

Tip

The more specific the filter, the smaller will be the number of users or groups that RStudio Connect has to handle.

For example, if one wanted to exclude users with uidNumber value greater than 1000, the base filter could be:

UserFilterBase = (&(objectClass=posixAccount)(uidNumber<1000))

Note

The filter base must always contain the object class, otherwise any objects could be returned as invalid users or groups.

The more characteristics of your LDAP users and groups you add to the filters, the smaller the number of objects visible to RStudio Connect and faster the searches tend to be.

For example, you can match groups with a certain name prefix (in this case "RSTUDIO_"):

GroupFilterBase = (&(objectClass=group)(cn=RSTUDIO_*))

If necessary, please consult with your LDAP or Active Directory administrator to learn more of the characteristics that differentiate users and groups.

You can see more examples of LDAP queries to be used as filters in this link.

Disabling Automatic Group Membership Lookup#

Disabling the option LDAP.GroupsAutoLookup will revert RStudio Connect access controls as they worked in past releases, which reaches LDAP/AD directly to validate group memberships, instead of using the local database.

Warning

Disabling automatic membership lookup will result in loss of functionality. This option should be used only temporarily while the cause of a poor login experience is determined or until a more specific configuration is found for the integration between LDAP and RStudio Connect.

Without automatic group lookup enabled:

The credentials in RStudio-Connect-Credentials HTTP header and in Shiny app's session$groups will not contain groups.
The options Authorization.ContentCredentialsUseDN and Authorization.ContentCredentialsUseGUID will not work and must be disabled.
LDAP.GroupsAutoProvision cannot be used and must be disabled.
The Public API to list content available to a user may have an outdated view of the user's group memberships, if at all.
Groups will be stored in RStudio Connect only when added by an administrator.
Group names will only be updated during subsequent searches for groups in RStudio Connect which include the modified group among the search results.
Groups memberships are not stored locally in RStudio Connect. Changes to group memberships are detected in the interval of time defined by the option LDAP.CacheTTL.

With automatic group lookup (default):

All features mentioned above are available.
Groups memberships are always stored in RStudio Connect and kept in sync.
Groups are updated on each and every successful login attempt.
Groups not yet seem by RStudio Connect are created on each successful login attempt when LDAP.GroupsAutoProvision is enabled.

Advanced LDAP and Active Directory Configuration#

Integrating with Multiple LDAP/AD Servers#

Adding Multiple Configuration Sections#

LDAP/AD Settings by Category#

Connectivity Settings#

ServerAddress#

TLS#

StartTLS#

TLSCACertificate#

ServerTLSInsecure#

BindDN and BindPassword#

AnonymousBind#

User Settings#

UserSearchBaseDN#

UserObjectClass#

UserFilterBase#

UniqueIdAttribute#

UsernameAttribute#

UserFirstNameAttribute#

UserLastNameAttribute#

UserEmailAttribute#

UserRoleAttribute#

Group Settings#

GroupSearchBaseDN#

GroupObjectClass#

GroupFilterBase#

GroupUniqueIdAttribute#

GroupNameAttribute#

PermittedLoginGroup#

Performance Considerations#

Search Base DN (users and groups)#

Object Class and Base Filters (users and groups)#

Disabling Automatic Group Membership Lookup#

`ServerAddress`#

`TLS`#

`StartTLS`#

`TLSCACertificate`#

`ServerTLSInsecure`#

`BindDN` and `BindPassword`#

`AnonymousBind`#

`UserSearchBaseDN`#

`UserObjectClass`#

`UserFilterBase`#

`UniqueIdAttribute`#

`UsernameAttribute`#

`UserFirstNameAttribute`#

`UserLastNameAttribute`#

`UserEmailAttribute`#

`UserRoleAttribute`#

`GroupSearchBaseDN`#

`GroupObjectClass`#

`GroupFilterBase`#

`GroupUniqueIdAttribute`#

`GroupNameAttribute`#

`PermittedLoginGroup`#