Advanced LDAP and Active Directory Configuration

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

In this appendix:

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

Posit 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 Posit 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 Posit Connect and there is not a common LDAP domain.

  • Two or more LDAP servers work in contingency to each other for achieving high availability.

All sections must consistently declare group sources to be local (user-managed) or remote (provider-managed). Local groups are considered enabled when LDAP.GroupNameAttribute and LDAP.GroupSearchBaseDN are not configured. Local groups can be disabled entirely with Authorization.UserGroups.

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.

Here is a sample configuration using two LDAP sections.

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

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

By default, when there are multiple LDAP/AD server sections configured, such servers will be used to work in contingency to each other for achieving high availability. When the goal is to have different LDAP/AD servers that contain different sets of users or groups, set Authentication.MirroredLDAPServers to false.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authentication]
MirroredLDAPServers = false

Distributed users and groups across multiple LDAP/AD servers.

When Authentication.MirroredLDAPServers is set to false and the multiple LDAP/AD servers configured have different sets of users and groups, consider the possibility that some users or groups may exist in more than one LDAP/AD server. For example, different departments may be represented by different groups in different servers, but some users might be shared across both or migrating between groups over time.

To prevent user and group duplicates, please consider using proper attributes for LDAP.UniqueIdAttribute and LDAP.GroupUniqueIdAttribute to help define the uniqueness of users and groups.

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 Posit Connect:

Connectivity Settings

These settings determine how Posit 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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
ServerAddress = ldap.company.com:389
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
ServerAddress = ldaps.company.com:636
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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, Posit 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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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 Posit 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 Posit 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 Posit Connect should use.

UserSearchBaseDN

LDAP.UserSearchBaseDN (required) is the starting point from which Posit Connect will search for user entries in your LDAP/AD server. The “deeper” this location is in your LDAP server, the faster Posit 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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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 Posit 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 Posit 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. Posit Connect will try to detect this, and it will not start if problems are found. Before starting up Posit 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. Posit 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. Posit 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 Posit 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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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 Posit 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 Posit 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 Posit 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 Posit 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 Posit Connect should use.

GroupSearchBaseDN

LDAP.GroupSearchBaseDN is the starting point from which Posit Connect will search for group entries in your LDAP/AD server. The “deeper” this location is in your LDAP server, the faster Posit 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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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 Posit 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. Posit Connect will try to detect this and it will not start if problems are found. Before starting up Posit 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. Posit 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. Posit 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
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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=scientists,ou=group,dc=company,dc=com
; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
PermittedLoginGroup = cn=admins,ou=group,dc=company,dc=com
PermittedLoginGroup = cn=sales,ou=group,dc=company,dc=com
PermittedLoginGroup = cn=analysts,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 Posit Connect.

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

  • Define how much of the LDAP “tree” is visible to Posit Connect with a deeper search base. Is there a single particular location within LDAP under where Posit Connect users and groups are organized?

  • Define how many objects are visible to Posit Connect with a more specific base filter. Is there any defining characteristics of Posit 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 Posit 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 Posit Connect and faster the searches tend to be.

Tip

As a rule of thumb, Posit 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:

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

Tip

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

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

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration"]
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 Posit Connect and faster the searches tend to be.

For example, you can match groups with a certain name prefix (in this case “POSIT_”):

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

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 Posit 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 Posit Connect.

With automatic group lookup (default):

  • All features mentioned above are available.

  • Groups memberships are always stored in Posit Connect and kept in sync.

  • Groups are updated on each and every successful login attempt.

  • Groups not yet seen by Posit Connect are created on each successful login attempt when LDAP.GroupsAutoProvision is enabled.

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 Posit Connect only when added by an administrator.

  • Group names will only be updated during subsequent searches for groups in Posit Connect which include the modified group among the search results.

  • Groups memberships are not stored locally in Posit Connect. Changes to group memberships are detected in the interval of time defined by the option LDAP.CacheTTL.