Active Directory with Service Credentials (double-bind)#
RStudio Connect can integrate with your company's Active Directory (AD) infrastructure using the LDAP authentication provider.
Using this integration, user authentication, group search, and user search requests will be directed to your LDAP service.
RStudio Connect requires service credentials to execute user and group searches in Active Directory.
If you are not able to obtain service credentials, you can
still use Active Directory solely for authentication purposes
with your own user credentials by configuring RStudio Connect
Active Directory without Service Credentials
Active Directory Example With Service credentials#
This sample configuration (partial) assumes the standard schema for Active Directory.
; /etc/rstudio-connect/rstudio-connect.gcfg [Authentication] Provider = ldap [LDAP "Sample AD Configuration With Service Credentials"] ; Connectivity ; For legacy SSL (ldaps) use these: ServerAddress = ldaps.company.com:636 TLS = true ; Or for TLS (StartTLS extension) use these: ; ServerAddress = ldap.company.com:389 ; StartTLS = true TLSCACertificate= /etc/ssl/cert/ca.pem ; For TLS/SSL testing purposes only: ; ServerTLSInsecure = true ; Service credentials (recommended): BindDN = "EXAMPLE\\admin" BindPassword = "XXXXXXXX" ; Or anonymous bind (less secure): ; AnonymousBind = true ; 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" ; Enable this for a better user experience, unless ; managing a large number of groups is a concern: ;GroupsAutoProvision = true ; When attempting to troubleshoot a problem relating to LDAP, ; you can enable more verbose logging by enabling the following line ;Logging = true
Active Directory users are created in RStudio Connect upon the first successful login attempt. In addition, users can also be created ahead of their first login by adding them as users within the "people" tab of the RStudio Connect dashboard or by using the Connect Server API.
can be used to disable the registration through login behavior.
; /etc/rstudio-connect/rstudio-connect.gcfg [LDAP "corporate Active Directory"] RegisterOnFirstLogin = false
RStudio Connect will collect the user's credentials and forward them to the Active Directory server which will validate the authentication. If valid, the remote user's information will be returned to the RStudio Connect server.
Users within RStudio Connect are assigned Roles.
Users are assigned the role specified by the
setting or one defined by the User Role Mapping if configured.
Additionally, an administrator can reassign the role from within the dashboard or via the User Manager CLI.
Usernames are controlled by your Active Directory server. However, RStudio Connect imposes some additional restrictions on the usernames it supports:
- A username or DN containing a forward slash (
/) is not supported.
- The following values are prohibited:
Usernames in Active Directory do not need to be unique. A user is uniquely identified
by the attribute defined in
(Users with the same username are differentiated via their personal passwords.)
Duplicate usernames are a reality of large Active Directory deployments with multiple servers, which implies multiple Active Directory server configurations in RStudio Connect.
Active Directory global catalog configurations can also return duplicate usernames. However, that happens over a single connection which means a search for a username may return multiple hits. This configuration is not currently supported by RStudio Connect.
The RStudio Studio IDE does not support duplicate usernames when publishing to the same RStudio Connect host. However, it is unlikely that two users with the same usernames will be sharing the same IDE account or workstation.
Duplicate users may have adverse affects on content that tracks the user credentials. Please refer to the Credentials for Content in the Advanced Users and Group Topics appendix for alternatives under this condition.
The following user information is required:
- First name.
- Last name.
- Email address.
Different Active Directory attributes may be used for each of these fields, but in general, all user attributes are provided by Active Directory, and they should all be present in the RStudio Connect configuration.
If your Active Directory server cannot provide some of these, be sure to not define the respective attributes in the RStudio Connect configuration, so that the profile information can be entered manually by users. Otherwise, the profile values will not be editable in RStudio Connect and will remain blank.
When changes are made to a user's name, email address, or username in your Active Directory system, these changes will automatically propagate to RStudio Connect:
The next time that the user logs into RStudio Connect.
When the user is returned in a search result while adding new users.
As RStudio Connect synchronizes Active Directory group memberships.
Editing User Attributes#
A username is the primary means of authentication. Therefore, it is required in the configuration, and never editable.
By default, the setting
has a value of
AdminAndSelf, permitting users and administrators to
manage these editable user profile information not configured to be managed by
Admin if profile editing should be restricted only to administrators.
It is recommended that if you disable
with a value of
false, that you also configure
Admin. A value of
Admin means that users created by the administrator,
cannot be changed by non-administrators.
Editing User Roles#
User roles are only editable in RStudio Connect if Automatic User Role Mapping is not configured, and the Active Directory authentication provider is not configured to send roles in as part of the user profile.
Automatic User Role Mapping#
RStudio Connect offers ways to map their user information to valid roles when users login. This can be done with roles defined as part of the user profile or via Active Directory group memberships.
Using Group Memberships#
This option is not supported when using Locally Managed Groups.
Use the configuration option
to enable user role mapping via groups.
When group mapping is enabled, configuration options to receive roles from
the authentication provider as part of the user profile information will be
ignored and RStudio Connect will fail to start if
is also enabled.
In the following example group names are used. Viewer mapping is purposely left
out so that the remaining of the users will be assigned the based on the option
which defaults to
; /etc/rstudio-connect/rstudio-connect.gcfg [Authorization] UserRoleGroupMapping = true PublisherRoleMapping = "cn=Developers,ou=Groups,dc=example,dc=com" AdministratorRoleMapping = "cn=Dev-Leaders,ou=Groups,dc=example,dc=com" AdministratorRoleMapping = "cn=IT-Administrators,ou=Groups,dc=example,dc=com"
Using User Profile Roles#
Use the configuration option
to enable user role mapping via a user profile attribute from your authentication provider.
option should also be used if the values you receive from your authentication provider do not
match the default expected values of
User roles can be used directly from your authentication provider without
the need of mapping values as long as it only returns the values of
administrator to define roles in RStudio
# LDAP Record with no role mapping needed uid: RUser rsc-role: administrator # RStudio Connect Configuration to enable RUser [LDAP "My LDAP Server Name"] UserRoleAttribute = rsc-role # LDAP Record with role mapping needed uid: RUser2 rsc-role: connect-administrator # RStudio Connect Configuration to enable RUser2 [LDAP "My LDAP Server Name"] UserRoleAttribute = rsc-role [Authorization] UserRoleMapping = true AdministratorRoleMapping = connect-administrator ; PublisherRoleMapping = connect-publisher ; assuming the values continue as such ; ViewerRoleMapping = connect-viewer
When mapping is enabled, each role can be mapped to one or more values specific
to your organization using the configuration options
In the following example the authentication provider returns department names:
; /etc/rstudio-connect/rstudio-connect.gcfg [Authorization] UserRoleMapping = true ViewerRoleMapping = "HR" ViewerRoleMapping = "Marketing" PublisherRoleMapping = "Engineering" AdministratorRoleMapping = "IT"
Multiple User Role Mappings#
When there are multiple matches between the configured mapping and the user or group information sent by the authentication provider, the role with the most privileges is selected. This behavior makes it easy to promote users to a new role.
If there are concerns about security, a more restrictive behavior can be
used in these scenarios with the configuration option
When enabled, it will cause the least privileged role to be selected.
Active Directory Groups#
RStudio Connect automatically associates users to the groups already present in RStudio Connect for access control purposes as indicated by the existing group memberships in Active Directory.
Nested groups are not supported for Active Directory.
RStudio Connect needs to be configured to automatically recognize Active Directory groups. If the settings for groups are omitted from the configuration, only Locally Managed Groups will be available.
Active Directory groups must be managed directly through your Active Directory provider. RStudio Connect does not support management of Active Directory groups.
A reference to a Active Directory group is stored in RStudio Connect when manually added via "people" in the dashboard, via Connect Server API or automatically on log-in with the auto-provision option enabled.
Changes made to group names and Distinguished Named will automatically propagate to RStudio Connect:
The next time that a member of the groups logs into RStudio Connect.
When the group is returned in a search result while adding new groups.
As RStudio Connect synchronizes Active Directory group memberships.
Active Directory groups are uniquely identified by the attribute defined in
LDAP.GroupUniqueIdAttribute (with the default of
For information on how to configure this setting for your
specific Active Directory server, see
Manual Group Provisioning#
Admins may use the "People" tab within the RStudio Connect dashboard to "add" references to groups from the proxy. Group membership of RStudio Connect users will be tracked for only these groups and not the entire list of groups that are returned from Active Directory.
This is the default behavior, and a good option when the RStudio Connect users are associated with a large number of groups, but only some of them are useful for content access control purposes.
Care should be taken when removing groups via "people" in the dashboard or via Connect Server API. Removing a group will also remove all associations between the group being removed and existing content.
Automatic Group Provisioning#
In addition to delegating group membership management to Active Directory, RStudio
Connect can also delegate the management of groups themselves. By using
RStudio Connect will automatically add references to groups based on the list of group memberships received from Active Directory during authentication.
With this option enabled groups are provisioned in RStudio Connect when the first member is added and remain there indefinitely, even after the last member has been removed, so that any access to content is preserved for a future member of those groups.
Removing stale or unused groups can be done via the dashboard, via the
RStudio Connect Server API, or ultimately via the
Active Directory Group Membership Synchronization#
RStudio Connect prefetches all group memberships during every authentication. After that, the group memberships for Active Directory users in RStudio Connect are updated in a regular interval to ensure that content access granted via groups is synchronized with Active Directory.
By default, RStudio Connect will update each user individually every 4 hours,
obtaining all their group memberships in the same way it is done during
authentication. This interval can be modified via the configuration setting
In previous releases of RStudio Connect, access controls would validate group memberships directly with the Active Directory server at access time. This approach prevented RStudio Connect from having a complete picture of the group memberships for a given user, what some situation resulted in reduced functionality when using LDAP authentication compared to other authentication providers.
If you are running an earlier release of RStudio Connect, an automatic
synchronization for all users will take place immediately after an upgrade.
RStudio Connect uses a best-effort approach to have all users updated within the
but without disrupting the regular usage of the service. This process happens
only once per installation and will not be needed in future version upgrades.
Please see the Performance Considerations in the Advanced LDAP / AD appendix for ways to optimize Active Directory search performance in RStudio Connect if you observe a noticeable impact on the service such as:
Unusual delays during user log in.
Modifications made to groups in Active Directory not being reflected in Connect after the interval configured in
Issues with content with scheduled email delivery that include member of Active Directory groups.
Excess of activity or usage on the Active Directory service.
Warnings about the membership update process in the logs.
The shorter the membership update interval is, the greater is the computational cost of running the synchronization. On the other hand, large or busy environments may need a longer update interval to be able to keep group memberships in sync consistently. The default interval value of 4 hours aims to offer a good balance between cost and user experience for most customers.
Use Active Directory Groups To Limit Access to RStudio Connect#
By using Active Directory groups it is also possible to restrict which users are
allowed in RStudio Connect based on their group memberships, see the setting
for more details.
Scheduled Email Delivery & Active Directory Group Memberships#
When using Active Directory groups associated to content, the recipients of content configured for scheduled email delivery will include all active and unlocked RStudio Connect users members of that group as well as all other Active Directory users members of the group with valid email addresses.
This functionality does not require or depend on the membership synchronization.
Locally Managed Groups#
You can still use groups in RStudio Connect if you decide to not configure support for Active Directory groups.
Locally managed groups have no relation with Active Directory groups.
These groups are local to RStudio Connect, they can be created via the Dashboard or via the Connect Server API. Group memberships must also be managed using the same means.
If you do not want groups at all in RStudio Connect, set the
configuration option to