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

LDAP and Active Directory support in RStudio Connect has the following constraints:

  • A user is uniquely identified by the attribute defined in LDAP.UniqueIdAttribute. This defaults to "DN" (Distinguished Name) which offers a broad compatibility with different LDAP products but has some known limitations. For information on how to configure this setting for your specific LDAP server, see UniqueIdAttribute.

  • The same limitation applies to LDAP groups which use LDAP.GroupUniqueIdAttribute to define the attribute which uniquely identifies them, also with the default of "DN".

  • The following user information is required: first name, last name, email address, and username. Different LDAP/AD attributes may be used for each of these fields.

  • When changes are made to a user's name, email address, or username that are in your LDAP/AD sytem, the changes do not automatically propogate to RStudio Connect. However, the user information updates the next time that the user logs into RStudio Connect after the LDAP/AD update is made.

  • A username or DN containing a forward slash (/) is not supported.

There are additional constraints when LDAP bind credentials are not configured in RStudio Connect:

  • The DN of a user must contain their username (i.e. must utilize the LDAP.UsernameAttribute). 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 bind credentials when the DN does not contain the username.

  • Searches will only include users who have previously logged into RStudio Connect.

  • Groups will be unavailable.

When attempting to troubleshoot a problem relating to LDAP, you can enable more verbose logging by enabling LDAP.Logging in any LDAP configuration section.

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

Defining an LDAP or AD section

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

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.

Make sure that 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"]
...

Each of these sections will have a variety of configuration settings, which are explained below.

Complete Configuration Examples

IMPORTANT: These examples use a local LDAP server with a fake organization, hierarchy, and credentials. You will need to adjust these samples to your environment. Talk to your LDAP administrator if you need help with your organization's LDAP hierarchy.

Here are four complete LDAP configuration examples.

  • Active Directory example with bind credentials (recommended)
  • OpenLDAP example with bind credentials (recommended)
  • Active Directory example without bind credentials
  • OpenLDAP example without bind credentials

Activate Directory Example With Bind Credentials

This sample configuration assumes the standard schema for Active Directory.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample AD Configuration With Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
BindDN = "EXAMPLE\\admin"
BindPassword = "XXXXXXXX"
; Users
UserSearchBaseDN = "OU=Users,DC=example,DC=com"
UserObjectClass = "user"
UniqueIdAttribute = "objectGUID"
UsernameAttribute = "sAMAccountName"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"
; Groups
GroupSearchBaseDN = "OU=Users,DC=example,DC=com"
GroupObjectClass = "group"
GroupUniqueIdAttribute = "objectGUID"
GroupNameAttribute = "sAMAccountName"

Note: the Groups portion and the setting that follow it can be omitted if there is no intention to use Active Directory groups.

OpenLDAP Example With Bind Credentials

This sample configuration assumed a very simple OpenLDAP structure detailed below.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample OpenLDAP Configuration With Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
BindDN = "cn=admin,dc=example-openldap"
BindPassword = "XXXXXXXX"
; Users
UserSearchBaseDN = "ou=People,dc=example-openldap"
UserObjectClass = "posixAccount"
UniqueIdAttribute = "entryUUID"
UsernameAttribute = "uid"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"
; Groups
GroupSearchBaseDN = "ou=Group,dc=example-openldap"
GroupObjectClass = "posixGroup"
GroupUniqueIdAttribute = "entryUUID"
GroupNameAttribute = "cn"

Note: the Groups portion and the setting that follow it can be omitted if there is no intention to use LDAP groups.

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

dn: uid=management,ou=Groups,dc=example-openldap
objectClass: posixGroup
sn: Doe
memberUid: john
cn: Management
entryUUID: d7682e34-d688-99f0-1037-58dac1afa3d6

Active Directory Example Without Bind Credentials

This sample configuration is a modified version of the Active Directory sample above without bind credentials or group support.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample AD Configuration Without Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
; Users
UserSearchBaseDN = "OU=Users,DC=example,DC=com"
UserObjectClass = "user"
UniqueIdAttribute = "objectGUID"
UsernameAttribute = "sAMAccountName"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"

OpenLDAP Example Without Bind Credentials

This sample configuration is a modified version of the OpenLDAP sample above without bind credentials or group support.

; /etc/rstudio-connect/rstudio-connect.gcfg
[LDAP "Sample LDAP Configuration Without Bind"]
; Connectivity
ServerAddress = 127.0.0.1:389
; Users
UserSearchBaseDN = "ou=People,dc=company,dc=com"
UserObjectClass = "posixAccount"
UniqueIdAttribute = "entryUUID"
UsernameAttribute = "uid"
UserEmailAttribute = "mail"
UserFirstNameAttribute = "givenName"
UserLastNameAttribute = "sn"

LDAP or AD Configuration Settings

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 "LDAPS" or "Opportunistic TLS". 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 certficate 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 users to add as collaborators, or sending email documents will only work partially.

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

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

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.

UserSearchBaseDN

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

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 flexible when searching for user objects in complicated LDAP hierarchies.

Either LDAP.UserObjectClass or UserFilterBase must be defined. If UserFilterBase is unset, it is given a default value of objectClass={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))

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 configurarion) 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.

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

Note: Roles are no longer editable via Dashboard if assigned automatically.

If you prefer to map the values of a field to RStudio Connect user roles, you can use the Automatic User Role Mapping to map custom values returned during authentication or even group distinguished names (DN) to valid user roles in RStudio Connect.

Note: When assigning roles via groups, the configuration of the role mappings is similar to LDAP.PermittedLoginGroup.

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

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

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.

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 flexible when searching for group objects in complicated LDAP hierarchies.

Either LDAP.GroupObjectClass or GroupFilterBase may be defined. If GroupFilterBase is unset, it is given a default value of objectClass={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))

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

GroupSearchBaseDN

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

Examples

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