Authentication Integration with SAML#
If your company's authentication infrastructure supports SAML, you can use the RStudio Connect SAML authentication provider to integrate the two systems.
Using this integration, user authentication will be done with your Identity Provider.
SAML Integration Example#
The SAML configuration appendix contains information about each SAML configuration option.
Though it is not typically required, the
configuration option is required when using SAML to securely restrict SAML
authentication to a specific address.
; /etc/rstudio-connect/rstudio-connect.gcfg [Server] Address = rstudio.company.com [Authentication] Provider = "saml" [SAML] IdPMetaDataURL = "https://keycloak.lvh.me/auth/realms/rsconnect/protocol/saml/descriptor" IdPAttributeProfile = default ; 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 SAML, ; you can enable more verbose logging by enabling the following line ;Logging = true
In the example above, the value for
IdPAttributeProfile correspond to a
predetermined set of values matching the attributes to be assigned by your Identity Provider.
If you need more details about these individual values, please see the
section below on Using Attribute Profiles.
We provide other examples of SAML configuration at the bottom if your environment constraints ask for a more complex one.
Some IdPs will require you to manually enter information about RStudio Connect as the first step of the SAML configuration. In this situation, you should start with your Identity Provider Configuration, and once done proceed with the RStudio Connect Service Provider Configuration.
Other IdPs will require you to provide a Service Provider (SP) metadata as one of the first steps of the configuration. In this situation, the RStudio Connect Service Provider Configuration should be done first, and you must at least obtain the Identity Provider SAML metadata URL, or file copy of the metadata, or the individual IdP information required by RStudio Connect. Only then, you will be able to obtain the RStudio Connect Service Provider metadata.
RStudio Connect supports SAML 2.0 only.
User searching in RStudio Connect will only search users which have logged in or created via the RStudio Connect Server API.
User group searching in RStudio Connect will only search groups which have been populated from user logins or created via the RStudio Connect Server API.
It is highly recommended that RStudio Connect be configured to listen on a port secured with TLS to make sure SAML login assertions are posted to the RStudio Connect server in a secure manner. See the HTTPS configuration appendix for a list of the options available when configuring TLS.
Authentication requests initiated by RStudio Connect are valid for 15 minutes. If a response to an expired request is posted from an Identity Provider for a user, the login will fail and the user will need to initiate a new request.
The number of authentication requests initiated by RStudio Connect is limited to 1000 concurrent attempts after which any other requests will be refused until any responses which correlate with open requests are processed or some of those requests expire.
Identity Provider Configuration#
Almost all IdPs will require you to define and configure the service providers that they should interact with, including RStudio Connect. They may use different terms, but there are three pieces of information you will need to provide to the IdP.
The first two items below can sometimes be configured in the IdP by way of providing the metadata XML document for the SP. This is generally preferable when available. Once done with your IdP configuration, see the Service Provider Configuration section for more details.
Service Provider EntityID -- This is a string that uniquely identifies RStudio Connect as a service provider to the IdP. This might be labeled in other ways such as, Entity ID, Name, Destination, Audience, Audience Restriction, etc. This is typically a URL to the metadata provided by the SP but doesn't need to be.
You should use a value of
https://<hostname>[:port]/__login__/samlfor RStudio Connect, replacing
portas appropriate. These should match what is specified in the
It is important that when using the above URL as the entity ID it must not contain a trailing
/character; this will prevent logins from working as the audience field provided by the IdP will not match the entity ID that RStudio Connect will use.
It is not required that the IdP be able to access this URL. It means that RStudio Connect is not required to be running when you are asked for this value.
Assertion Consumption Service -- This is a URL in the service provider where the IdP will post authentication responses (also called assertions). This is important when initiating an authentication at the IdP. This may also be labeled as Single sign on URL, SSO URL, ACS URL, etc.
You should use a value of
https://<hostname>[:port]/__login__/saml/acsfor RStudio Connect, replacing
portas appropriate. These should match what is specified in the
Make sure the ACS URL you provide does not contain a trailing slash. Having one will prevent logins from working.
Attribute Mapping -- This is the mapping of fields known within the IdP to the attribute names that will be used for them in authentication responses. They are usually specified in name/value pairs, though they may include a format specification. RStudio Connect handles all formats as strings.
Each name is the string by which its value will be known in authentication responses and must match the values specified in RStudio Connect.
If you are using the
IdPAttributeProfileas in the example with
default, look at the Using Attribute Profiles section for the values you should manually define in the IdP mapping. Not using
IdPAttributeProfileis possible, but it requires defining all attribute mapping with individual settings for each user attribute. Visit the link above for a complete list.
RStudio Connect SAML MetaData#
Some IdPs can configure basic information about a service provider from its
metadata file. RStudio Connect will serve its SAML metadata from the
https://<hostname>[:port]/__login__/saml endpoint (the same as RStudio
Connect's entity ID). If the IdP accepts a URL for the SP's metadata (and the
IdP has the means to reach RStudio Connect), you should use the entity ID as
the URL. If the IdP accepts an upload of the SP's metadata file, you can use
curl command to get the SAML metadata from RStudio Connect as follows:
curl https://localhost:3443/__login__/saml --output metadata.xml
The above assumes you are executing
curl from the machine where RStudio
Connect is running and will write the metadata XML document to a file called
metadata.xml in the current directory. The same command, or even a browser,
may be used from anywhere that RStudio Connect is accessible.
RStudio Connect will only be able to serve its metadata when running with minimally valid SAML configuration with the IdP information defined.
RStudio Connect Service Provider Configuration#
There are two ways to configure the information RStudio Connect needs about your SAML Identity Provider (or IdP), either by using the IdP's metadata or by using specific configuration options. Using the metadata is highly recommended for an easier integration with your IdP.
User Attribute Mapping is an optional step of the configuration.
It is only needed when using
SAML. IdPAttributeProfile is not sufficient
and needs to be customized.
Using an IdP's Metadata#
To configure an IdP by using a local copy of its metadata file, use the
option. Alternatively, the
option may be set to either an HTTPS (or HTTP) URL from which the metadata may
be retrieved from the IdP.
RStudio Connect requires that the SAML IdP be configured to sign all the
messages it sends. As such, the metadata for the IdP must contain a signing
certificate. Or, if you are using the specific options, the
option is required.
; /etc/rstudio-connect/rstudio-connect.gcfg [SAML] IdPMetaDataURL = https://idp.example.com/saml/metadata
tells RStudio Connect to pull the metadata for the IdP from the given URL, whereas
; /etc/rstudio-connect/rstudio-connect.gcfg [SAML] IdPMetaDataPath = /a/local/dir/idp.xml
tells RStudio Connect to read the metadata from the named, locally accessible file.
The retrieved, or read, metadata is cached while RStudio Connect is running. If the metadata expires during that time, the first time a user tries to login after the expiration will cause the metadata to be retrieved or read again. If the metadata is still expired (as would be if reading from a local file), that login will fail. Other login attempts will also fail so long as the metadata is expired. The existing user sessions will keep running normally. The expiration of metadata is used by some IdPs to allow new signing certificates to be issued so this is generally not a problem for URL-based metadata. If you are using file-based metadata, the error will persist until you update the metadata file. Once new, unexpired metadata is available, logins will succeed again.
The SAML metadata may contain settings for one or multiple IdPs. If your
metadata contain settings for more than one IdP the setting
SAML.IdPEntityID must be
configured with the entity ID matching the correct metadata entry for your
commonly requires this additional step.
Providing Specifics Yourself#
If there is some reason that an IdP's metadata cannot be made available to the
RStudio Connect server, you can provide the information yourself by using the
is used to identify the IdP. Since all identity providers must have a public
name, this entity ID, it is used to verify that SAML messages are being
received from the correct system.
option is used to tell RStudio Connect where to send (via
POST or redirect)
authentication requests for a user attempting to log in. The IdP system must
be listening for this URL for SP-initiated logins. In the case where RStudio
Connect is configured for IdP-initiated logins only, this must be the
IdP's user login page.
specifies the public side of the key that the IdP will use to sign the
messages it sends to RStudio Connect. It may be the path to a PEM file or the
raw, Base64 encoded certificate. When not configuring IdP information from
metadata, this option must be specified.
SAML.IdPSigningCertificate, if you use the individual options,
you must not specify the
option or the
option, as that will override these. A warning is logged during RStudio
Connect startup if this condition exists.
Other SAML Options#
Depending on other IdP configuration or security requirements, you may need to add a few more options to the RStudio Connect SAML configuration in order to proceed:
RStudio Connect supports at least a subset of SAML called Interoperable SAML.
Notably, certain functionalities are currently absent:
Certificate chain validation
RelayState URL handling (not part of the SAML standard)
Supporting Encrypted Assertions and Responses#
If you (or your IdP) want the IdP to post encrypted SAML responses to complete
login operations, you need to make a security key pair available to both
sides. The IdP must be given the public certificate side of the key pair; how
this is done varies by IdP. The key must be an RSA key pair. The
ssh-keygen commands are the most common tools to use to generate a new key
pair. Refer to the documentation for your tool of choice; the goal is to
create two PEM files, one with the private key and one with the public
configuration option to provide the private part of the key pair to RStudio
Connect. It must be provided if you want encryption support to be enabled. It
must be a path to an RSA private key file in PEM format.
Use the option
to provide the public certificate to RStudio Connect. Do this to include the
certificate in the SP metadata that RStudio Connect will produce.
Supporting Signed Authentication Requests#
All SAML responses must be signed by your IdP. This section is about whether or not RStudio Connect itself will send signed SAML messages to your IdP. In most cases this is not required and this section can be skipped.
If you (or your IdP) want RStudio Connect to sign the SAML authentication
requests used for the SP-initiated login flow, you need to make sure a security
key pair is available to both sides. The IdP must be given the public certificate
side of the key pair; how this is done varies by IdP. The key must be an RSA key
ssh-keygen commands are the most common tools to use to
generate a new key pair. Refer to the documentation for your tool of choice; the
goal is to create two PEM files, one with the private key and one with the public
The certificate and RSA private key used for encryption can also be used for signing requests. If you already have encryption configured, no additional keys will be needed.
configuration option to provide the private part of the key pair to RStudio
Connect. Either an encryption key or a signing key must be provided if you want
request signing support to be enabled. It must be a path to an RSA private key
file in PEM format.
Use the option
to provide the public certificate to RStudio Connect. Do this to include the
certificate in the SP metadata that RStudio Connect will produce.
RStudio Connect only accepts a single key pair. You can use a key pair for both encryption and signing requests or one just for signing. Different key pairs for signing and encryption are not currently supported.
You also need to know what is the signing method supported by your IdP. The
available options are
sha512. Your choice needs to be
configured in the
option. When in doubt, try
sha256 first which offers a good balance between
security and compatibility.
By using one of the signing methods listed above the RStudio Connect
metadata will contain a
"signing" certificate and will have the attribute
AuthnRequestsSigned with the
option to note whether you want RStudio Connect to use
POST binding (
or redirect binding (
false, the default) when RStudio Connect is to initiate
a single sign-on operation with your IdP. Redirect is the most common choice.
If you use
POST binding, RStudio Connect will return a hidden HTML form
which will automatically be submitted to the IdP single sign-on page, where
either the page will be displayed, or if a user is already logged in, continue
through the login process and log the user into Connect.
If the IdP is configured by its metadata, RStudio Connect will verify that the
IdP makes an SSO location available using the binding requested here. If the
IdP metadata indicates multiple bindings are supported, the
option controls which one will be used.
Single Sign-On Initiation#
The SAML specification allows for a single sign-on flow to be initiated by
either the IdP or SP. Use the
to control this. There are three possible values.
IdP -- This indicates that single sign-on may be initiated at the IdP only. In this mode, an end user must visit the sign-on page of their IdP and select RStudio Connect as the service provider to use.
In this mode, you will not be able to use the IdP's metadata to configure the IdP's information; you will need to use the separate configuration options. When the IdP is used to initiate authentication, this causes a problem when publishing from the RStudio IDE. Since the IDE can only know about RStudio Connect, RStudio Connect must respond by returning a "blind" redirect to to the IdP's sign-on page. This must be configured in the
IdPAndSP -- This indicates that single sign-on may be initiated by either the IdP or by RStudio Connect. In this case, note that the RStudio IDE will always use the service provider initiated flow. This is the default.
SP -- This indicates that single sign-on may be initiated only by RStudio Connect. In this mode, an IdP-initiated login will fail, since there would be no matching authentication request that RStudio Connect has sent out.
Name ID Format#
When a SAML IdP identifies an authenticated user to a service provider, that
user is (typically) identified by what SAML calls a "
NameID". There are four
possible formats this name ID may be in. The IdP may support multiple values
for this. Use the
to tell RStudio Connect which of them your IdP will use. This may be set to
unspecified; the last will be
used if this option is not provided. If you specify an IdP attribute profile
(see below) the NameID format in the profile will take precedence over this
If a NameID format is explicitly defined, either by using a profile or the
it will be included as part of the SAML SP metadata RStudio connect will serve
/__login__/saml URI. This is true even if the format is set to
unspecified. If the
is omitted, them the SP metadata will not mention
NameIDFormat. See the
SAML Metadata section for more details about SP metadata.
If the IdP is configured by its metadata and the metadata advertises the
formats supported by the IdP, RStudio Connect will verify that the value
specified by the
SAML.NameIDFormat or from
the IdP attribute profile option is supported by the IdP using the following
If the value configured for RStudio Connect is
unspecified, any values from the IdP will be accepted.
If the value configured for RStudio Connect is anything else, it will be accepted if it is present in the IdP list of formats. If the IdP list contains
unspecifiedand the Connect format is not in that list, then it will be accepted but a warning will be logged noting that the configuration may need to be adjusted. In this situation, this may or may not work, depending on your specific IdP.
User Attribute Mapping#
When a user is authenticated by an IdP, certain data about the user may be
included in the authentication response. These are most commonly called
attributes, assertion attributes or claims. So that RStudio Connect may
manage its user information correctly, it needs to understand these. Since
this mapping includes the Name ID, the appropriate
for that ID is also included in the profile.
User fields which are mapped from SAML assertion attributes are updated (if they change) on all subsequent successful logins.
RStudio Connect can automatically assign users to groups when SAML authentication assertion includes group membership information.
Using Attribute Profiles#
There are times when RStudio will know ahead of time what the field mapping for a particular IdP should be. When that is the case, an appropriate attribute profile will be available in RStudio Connect's database.
configuration option to specify the profile RStudio Connect should use. By
default, this enables the mapping of group membership information. If you want
to use a profile but do not want to use groups, set the
configuration option to
false. If you specify a profile, you cannot specify
any of the
options, as they will be overridden by the profile. A warning is logged during
RStudio Connect startup if this condition exists.
SAML.IdPAttributeProfile is specified, then it overrides any of the
other IdP attribute name options. See the
Appendix for more
Below is a description of each of the "default" profile and the assertion names expected shown as their individual settings equivalents. See the SAML Attributes section for details about the individual configuration options.
; /etc/rstudio-connect/rstudio-connect.gcfg [SAML] UniqueIDAttribute = NameID NameIDFormat = persistent UsernameAttribute = Username FirstNameAttribute = FirstName LastNameAttribute = LastName EmailAttribute = Email GroupsAttribute = Groups
The attribute profiles never define a
to be used with User Role Mapping. This configuration
option should be defined with a value in addition to the profile if role mapping
is wanted in a per-user basis (as opposed to a mapping by group memberships).
Specifying Attributes Yourself#
The matching of the SAML attribute names is case sensitive in RStudio Connect.
configuration options to set the names of the attributes to look for in
obtaining the related values. For each of these that are not specified (when
not using an attribute profile), RStudio Connect will assume management of the
fields, making them editable in the Connect dashboard. If you wish to make use
of group information, use the
option to set the name of the attribute to look for. This allows for users to
automatically be added to groups that are manually created within Connect.
will override the individual attribute settings. Make sure this setting is not defined.
You must include either the
option (or both) in your configuration. If you do not configure the username
attribute or if it is not provided by SAML or the authentication mechanism behind
it, RStudio Connect will create a new unique username for a user the first time
that user logs in. The username will be derived from the user's email address,
without the domain, adding a numeric suffix as needed for uniqueness. These
usernames are editable.
To use this functionality the setting
should be forced to have a blank value (
"") and the header which contains
the user's email must be configured in the setting
These generated usernames can later be modified by the users themselves or by an administrator as long as they remain unique. RStudio Connect will refuse to change the username otherwise.
Switching between configurations where duplicate usernames are possible to
one where the usernames are unique is strongly discouraged. If such change
is necessary, be sure to make usernames unique by using the
CLI tool before restarting RStudio Connect with the new configuration. See
the User Management CLI appendix for
Additional Group Attribute Options#
It is expected to be in the form of a single attribute containing a list of all groups that the user belongs to.
In the rare event that an IdP cannot list groups as a list of distinct values,
you can use the
configuration option to specify a separator string that will be used to split
a single value into a list. For example, if the groups attribute contains a
value of the form,
group_1|group_2, set the
configuration option to
| and RStudio Connect will break the one value into
the represented list of group names.
The authentication will happen entirely in within your SAML Identity Provider's infrastructure, which once completed, will return the remote user information to RStudio Connect.
Register on First Login#
By default, users can be created in RStudio Connect upon their first successful
login attempt. Accounts will be created with the role specified in the
setting (see User Roles) or via User
Role Mapping if configured. Otherwise, the role may be
specified as the user is manually added within the dashboard or via the RStudio
Connect Server API.
Disabling Register on First Login#
can be used to disable the registration through login behavior.
; /etc/rstudio-connect/rstudio-connect.gcfg [SAML] RegisterOnFirstLogin = false
Using this option requires users to be exclusively created via the RStudio Connect Server API.
Usernames are defined externally by the SAML authentication service provider.
However, RStudio Connect imposes some additional restrictions on the usernames it supports:
- The following values are prohibited:
The usernames returned by the SAML provider are not required to be unique when
Duplicate usernames 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 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.
If your SAML IdP does not have a notion of usernames, RStudio Connect can generate one based on the user's email address. See Generated Usernames for details.
In addition to the value specified for
NameIDFormat (as described above),
a user is uniquely identified in Connect by the attribute defined in
or the same field in the profile specified by
This defaults to
"NameID" which is a standard identifier for the
authenticated Subject which offers a broad compatibility with different
SAML Identity Providers. If your IdP is set up to use the transient
format for Name IDs, then this value must be specified to something other
Users are uniquely identified by their Unique ID in the IdP system. If RStudio Connect is presented with a Unique ID it has never seen, it will create a new user.
The value obtained from
must match exactly the field
unique_id used for creating new users via the
Connect Server API. Once the user is created, the RStudio Connect identity
guid) should be used for subsequent API operations with that user.
The Unique ID of a user requires a mapping to either the Name ID of the SAML subject or to an Identity Provider (or IdP) assertion attribute and, as such, is not editable in RStudio Connect.
Editing User Attributes#
User profile fields present in the SAML assertion are not editable in RStudio Connect.
A non-editable field can be forcefully updated before a login via the
usermanager CLI tool. See the User Management
A user's username, first name, last name, and email address may be mapped
from any SAML assertion attribute. If a mapping is not configured, the
corresponding field will be editable in RStudio Connect, subject to the
Changes to fields mapped to SAML assertion attributes for a user (e.g. their name, email address, or username) will not propagate to RStudio Connect until the next time that user logs in.
For fields with no attribute mapping, the
will control who can edit them. That option has a default value of
AdminAndSelf, permitting users and administrators to manage these user
profile attributes. Configure
Admin if profile editing should be restricted 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 SAML authentication provider is not configured to send roles in as part of the user profile.
Automatic User Role Mapping#
RStudio Connect can automatically assign roles to users based on information from SAML identity providers when users log in. Roles can be assigned from one of two sources: SAML group memberships, or SAML user profile attributes.
It is not possible to use both user profile attributes and group
memberships to determine user roles. RStudio Connect will not start if the
configuration options for both features,
are set to
Using Group Memberships#
Using SAML group memberships to determine user roles prevents you from using Locally Managed Groups.
To set user roles based on SAML group membership, set the configuration option
When this feature is enabled, use the configuration options
to specify the name of a group to be assigned that role. To assign a single role
to multiple groups, use the corresponding option multiple times, each time
specifying a single group name.
When Groups By Unique ID are used, the role mapping should give groups' Unique IDs instead of their names.
In the following example, the group
Developers is given the Publisher role,
and the groups
IT-Administrators are given the Administrator
role. No groups are explicitly given the Viewer role, but all other users will
be given that role via the
option, which defaults to
; /etc/rstudio-connect/rstudio-connect.gcfg [Authorization] UserRoleGroupMapping = true PublisherRoleMapping = "Developers" AdministratorRoleMapping = "Dev-Leaders" AdministratorRoleMapping = "IT-Administrators"
Using User Profile Attributes#
To set user roles automatically using an attribute from the SAML assertion,
specify an attribute name in the
configuration option. This attribute is never set automatically via IdP
attribute profiles; you must set it explicitly.
If the specified attribute contains the exact values
administrator, no other action is needed.
If the specified attribute does not contain the exact values
administrator, you must provide the expected values. To do
this, set the configuration option
true. Then, use the configuration options
to specify a value for each role. To specify multiple values for a role, use
the corresponding option multiple times.
In the following example, the department names in the
dept attribute are used to assign roles to users. Note that the Viewer role is given to both
; /etc/rstudio-connect/rstudio-connect.gcfg [SAML] ; [Other SAML IdP configuration properties] RoleAttribute = "dept" [Authorization] UserRoleMapping = true ViewerRoleMapping = "HR" ViewerRoleMapping = "Marketing" PublisherRoleMapping = "Engineering" AdministratorRoleMapping = "IT"
When the role attribute on a user's profile does not match any of the
configured values, the user will be assigned the default role. This defaults
viewer, and can be configured with
User role mismatches are included in the RStudio Connect logs when
SAML.Logging is enabled.
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.
SAML Group Membership Management#
RStudio Connect can be configured to automatically assign users to existing groups according to the list of group names sent by your SAML Identity Provider (IdP). For every login attempt the list of group names received will be compared with the current memberships the user has, adding the user as a member of newly listed groups and removing the user from groups no longer listed.
The list of groups sent by IdP will override any memberships defined manually or via the Connect Server API. However, these operations could still be used between login attempts to keep the group memberships in sync with the IdP.
Manual Group Provisioning#
Admins may use the "People" tab within the RStudio Connect dashboard to "add" references to SAML managed groups. Group membership of RStudio Connect users will be tracked for only these groups and not the entire list of groups that are returned from your SAML IdP.
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 memberships, RStudio Connect can also be configured to
automatically provision (create) new groups according to the list of group names
sent by the IdP for the user. This can be enabled by using
This means that groups not yet present will be created in RStudio Connect for a user when the user logs in. These groups remain provisioned 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
Switching Between Manual and Automatic Group Provisioning#
Groups created by automatic provisioning do not have owners while any groups created manually or via the Connect Server API are always associated with a user.
RStudio Connect will issue a warning on startup if the ownership of the existing groups does not match the provider configuration.
In these situations, either the group needs to be removed or group ownership
needs to be adjusted. This can be done with the
usermanager CLI tool with
alter command using the
The goal is that all groups automatically provisioned should be assigned an
owner if you intend to manage them in RStudio Connect. Conversely if you
intend to have all groups managed by the authentication provider their owners
should be removed. Also, you should remove any groups that do not make sense
in the new configuration and this can be done via the Connect dashboard, the
Connect Server API or the
usermanager. See the User
Management CLI appendix to learn more.
Locally Managed Groups#
If you do not want to use SAML groups, you can still use groups in RStudio Connect. These groups have no relation to groups in your IdP.
Locally-managed groups can be created in RStudio Connect's Dashboard or via the Connect Server API. Group memberships must be managed using the same means.
If you do not want groups at all in RStudio Connect, set the
configuration option to
Matching Groups' Identifiers#
By default, RStudio Connect will match the list of groups send by the SAML IdP against the names of the groups that exist in RStudio Connect. Some SAML providers do not send group names, using instead their unique identifiers (such as GUIDs).
Groups by Name#
When your SAML IdP sends group names, the default behavior of RStudio Connect to match groups using a case-sensitive string comparison can be used.
If groups are renamed within your SAML IdP, they will be recognized as new
groups. Depending on the setting for
SAML.GroupsAutoProvision, these new groups
will either be added or ignored. In no circumstances will the old group be
renamed or removed from content ACLs.
You can still rename a group in RStudio Connect to match the group name in your
IdP to preserve all associations with content. If a duplicate group with the
same name was created by auto-provision, this new group must be removed first.
Groups by Unique ID#
To support the scenario where your SAML IdP sends unique identifiers for groups rather than
their names, RStudio Connect can be configured to match these identifiers by using the setting
This is considered to be an advanced feature in RStudio Connect. Identifying groups by an identifier other than their name requires the use of the RStudio Connect Server API for all group management workflows. The RStudio Connect Dashboard does not allow group management in this scenario, except by the association of the group with some content, which is still possible.
A group identified by a unique identifier must be provisioned within RStudio Connect
using the Connect Server API. The API call allows for the association of the group's
unique_id (same one sent by the SAML IdP during authentication) with a user-friendly
name, in general the same name as used in the IdP. RStudio Connect will not enforce
unique group names in this condition.
Duplicate group names 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.
SAML.GroupsByUniqueId is enabled,
SAML.GroupsAutoProvision can NOT
be enabled. This would lead to the creation of groups without meaningful names
in RStudio Connect given that the IdP would only be providing a Unique ID.
Switching Between Group Identities#
GroupsByUniqueId should be enabled before you have any groups in
RStudio Connect. If any groups have already been created and you wish to use
this option, it is strongly recommended to run the
usermanager --groups --normalize-ids
command to make these existing groups functional under the new setting. See the
User Management CLI appendix to learn more.
usermanager command above should also be run if you decide to disable
GroupsByUniqueId in a later time.
Authenticating with SAML using Multiple Network Aliases#
By default, RStudio Connect will only allow SAML authentication for the
hostname, protocol and port configured in the
setting. This is the preferred, and most secure approach.
If you intend to allow the SAML authentication to be used from
multiple network aliases such as different DNS entries or through multiple
proxies or both in front and behind a firewall you must enable this via the
setting. Once enabled,
Server.Address will be ignored and HTTP headers will be
used instead to determine the server protocol, hostname and port.
We recommend that proxies add an
X-RSC-Request header to requests.
The value of the
X-RSC-Request header should be the absolute URL of the
original request made by the client (e.g.
Some proxies (like Amazon Web Services Elastic Load Balancer, for example), do
not make it possible to add custom headers. If the
X-RSC-Request header is
not supplied, the standard headers
X-Forwarded-Port are used in a "best effort" attempt to determine the
original request URL.
X-Forwarded headers are not appropriate when the proxy performs path
rewriting (e.g. serving beneath
X-RSC-Request when path-rewriting.
X-RSC-Request takes precedence when
X-RSC-Request and the
X-Forwarded headers are supplied.
In the absence of these headers, the
Host header will be used and the
protocol or scheme (
https) will be selected based on whether
or not TLS/SSL is configured and used for the authentication attempt.
Relying exclusively on headers for determining the service provider location for SAML has security risks. It is highly recommended that a proxy or other network service be placed in front of RStudio Connect that ensure it is not possible to send a request containing one of the headers listed above with a malicious address.
Other Configuration Examples#
In this example, the configuration uses the metadata with individual user attribute names.
; /etc/rstudio-connect/rstudio-connect.gcfg [SAML] IdPMetaDataURL = https://idp.example.com/saml2/metadata NameIDFormat = persistent UsernameAttribute = "Username" FirstnameAttribute = "FirstName" LastnameAttribute = "LastName" EmailAttribute = "Email" GroupsAttribute = "Groups"
This is a more complex example of SAML configuration. It uses individual
settings when a metadata is not available or cannot be used. Single sign-ons
can be initiated by the IdP only, Connect will redirect to a login page on the
IdP if the authentication is attempted first in Connect (which will happen
with the RStudio IDE), the signing certificate, encryption key and certificate
are paths to PEM files and because
transient is being used the
is something other than the
; /etc/rstudio-connect/rstudio-connect.gcfg [SAML] SSOInitiated = IdP IdPEntityID = https://idp.example.com/saml2/metadata IdPSingleSignOnServiceURL = https://idp.example.com/login IdPSigningCertificate = /path/to/sign.cer SPEncryptionKey = /path/to/rsa.key SPEncryptionCertificate = /path/to/pem.cer NameIDFormat = transient UniqueIDAttribute = "GUID" UsernameAttribute = "Username" FirstnameAttribute = "FirstName" LastnameAttribute = "LastName" EmailAttribute = "Email" GroupsAttribute = "Groups"