RStudio Connect can integrate with the SAML Identity Provider (or IdP) of your company's choice to perform user authentication and, optionally, user/group membership management. In the SAML world, RStudio Connect fulfills the role of service provider (or SP). Note that user searching in RStudio Connect will search local users only as SAML provides no such user search capability.

RStudio Connect supports SAML 2.0 only.

RStudio Connect will use SAML authentication if the Authentication.Provider setting has a value of saml.

; /etc/rstudio-connect/rstudio-connect.gcfg
Provider = saml

The SAML configuration apendix contains information about each SAML configuration option.

Note: Though it is not typically required, the Server.Address configuration option is required when using SAML as the authentication provider.

SAML support in RStudio Connect has the following constraints:

  • A user is uniquely identified in Connect by the attribute defined in SAML.UniqueIDAttribute or the same field in the profile specified by SAML.IdPAttributeProfile. 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 than NameID.

    Note: The value that identifies the user must be immutable during the user's entire lifetime. Otherwise Connect will not be able to identify the user and will create a new one. For this reason, usernames and email addresses should be avoided as UniqueIDs unless it is the only option, since those can change over time.

  • 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 Authorization.UserInfoEditableBy configuration option.

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

  • If configured, groups that the user belongs to may also be mapped from a named SAML assertion attribute. When user groups are mapped, provisioning of those groups in RStudio Connect is also available.

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

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

; /etc/rstudio-connect/rstudio-connect.gcfg
Logging = true

Defining a SAML Section

Start a SAML configuration with a SAML section header like the following:

; /etc/rstudio-connect/rstudio-connect.gcfg

Identity Provider Configuration

There are two ways to configure the information RStudio Connect needs about your SAML Identity Provider (or IdP), either by the IdP's metadata or by using specific configuration options.

Note: 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 SAML.IdPSigningCertificate option is required.

Using an IdP's Metadata

To configure an IdP by using a local copy of its metadata file, use the SAML.IdPMetaDataPath option. Alternatively, the SAML.IdPMetaDataURL option may be set to either an HTTPS (or HTTP) URL from which the metadata may be retrieved from the IdP.

For example,

; /etc/rstudio-connect/rstudio-connect.gcfg
IdPMetaDataURL =

tells RStudio Connect to pull the metadata for the IdP from the given URL, whereas

; /etc/rstudio-connect/rstudio-connect.gcfg
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 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.

Note: 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 entityID matching the correct metadata entry for your IdP.

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 SAML.IdPEntityID, SAML.IdPSingleSignOnServiceURL, and SAML.IdPSigningCertificate configuration options.

The SAML.IdPEntityID option 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.

The SAML.IdPSingleSignOnServiceURL 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.

The SAML.IdPSigningCertificate 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.

If you use these options, you must not specify the SAML.IdPMetaDataURL option or the SAML.IdPMetaDataPath option, as that will override these. A warning is logged during RStudio Connect startup if this condition exists.

Supporting Encrypted 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 openssl or 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 certificate.

Use the SAML.SPEncryptionKey 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 SAML.SPEncryptionCertificate to provide the public certificate to RStudio Connect. Do this to include the certificate in the SP metadata that RStudio Connect will produce. Providing this to RStudio Connect is not required for encryption support to work.

SAML Binding

Use the SAML.IdPSingleSignOnPostBinding option to note whether you want RStudio Connect to use POST binding (true) 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 SAML.IdPSingleSignOnPostBinding option controls which one will be used.

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 SAML.NameIDFormat option to tell RStudio Connect which of them your IdP will use. This may be set to transient, persistent, emailAddress or unspecified; the last will be used if this option is not provided. If you specify an IdP attribute profile with SAML.IdPAttributeProfile (see below) the NameID format in the profile will take precedence over this option.

If a NameID format is explicitly defined, either by using a profile or the SAML.NameIDFormat option, it will be included as part of the SAML SP metadata RStudio connect will serve from its /__login__/saml URI. This is true even if the format is set to unspecified. If the SAML.NameIDFormat option 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 rules:

  • 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 unspecified and 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.

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 SAML.SSOInitiated option 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.

    Note: 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 SAML.IdPSingleSignOnServiceURL configuration option.

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

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 Unique ID, the appropriate NameIDFormat for that ID is also included in the profile.

RStudio Connect can automatically assign users to groups when SAML authentication assertion includes group membership information. This is expected to be in the form of a single attribute containing a list of all groups, by name, that the user belongs to.

Note: Your SAML IdP may send the groups' identifiers instead of their names during login. This is true for Azure. In this situation, you should use the SAML.GroupsByUniqueId configuration option and manage your groups via the Connect Server API. This option also alters the values expected for role assignment via groups.

In the rare event that an IdP cannot list groups as a list of distinct values, you can use the SAML.GroupsSeparator 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 SAML.GroupsSeparator configuration option to | and RStudio Connect will break the one value into the represented list of group names.

If the groups attribute is mapped, RStudio Connect will adjust the group memberships of the user logging in to match the list provided in the assertion, adding the user to named groups when necessary and removing them from groups that are no longer listed.

If group membership information is not mapped from the IdP, they are still supported when using SAML authentication. In this case, they can be managed manually in the Connect dashboard or via the Connect Server API.

Note: When group membership is not sourced from the IdP, groups are local to RStudio Connect and have no relation to any external groups.

If you do not want groups at all, set the Authorization.UserGroups configuration option to false.

Note: SAML attributes in the authentication response are case sensitive.

There are two ways to tell RStudio Connect about how this data is mapped.

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.

Use the SAML.IdPAttributeProfile 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 SAML.IdPAttributeProfileGroups configuration option to false. If you specify a profile, you cannot specify any of the SAML.UniqueIDAttribute, SAML.NameIDFormat, SAML.UsernameAttribute, SAML.FirstNameAttribute, SAML.LastNameAttribute, SAML.EmailAttribute or SAML.GroupsAttribute options, as they will be overridden by the profile. A warning is logged during RStudio Connect startup if this condition exists.

Note: If the SAML.IdPAttributeProfile is specified, then it overrides any of the other IdP attribute name options. See the Appendix for more information.

Below is a description of each of the known profiles and the assertion names each expects shown as their configuration equivalents. See the SAML Attributes section for details about the individual configuration options.

The default Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
UniqueIDAttribute = NameID
NameIDFormat = persistent
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = Email
GroupsAttribute = Groups

The okta Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
UniqueIDAttribute = NameID
NameIDFormat = persistent
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = Email
GroupsAttribute = Groups

The onelogin Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
UniqueIDAttribute = NameID
NameIdFormat = emailAddress
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = NameID
GroupsAttribute = Roles

The azure Profile

; /etc/rstudio-connect/rstudio-connect.gcfg
UniqueIdAttribute = NameID
NameIDFormat = persistent
UsernameAttribute =
FirstNameAttribute =
LastNameAttribute =
EmailAttribute =
GroupsAttribute =

Configuring for JumpCloud

If you are using the RStudio Connect application in JumpCloud, you should use the following configuration values:

; /etc/rstudio-connect/rstudio-connect.gcfg
UniqueIDAttribute = NameID
NameIdFormat = emailAddress
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = NameID
GroupsAttribute = Groups

Note: A jumpcloud profile is not yet available in RStudio Connect.

Specifying Attributes Yourself

Use the SAML.UsernameAttribute, SAML.FirstNameAttribute, SAML.LastNameAttribute and SAML.EmailAttribute 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 SAML.GroupsAttribute 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.

You must include either the SAML.UsernameAttribute or the SAML.EmailAttribute option (or both) in your configuration. If you do not configure the username attribute, 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.

Note: The usernames returned by the SAML provider are not required to be unique when SAML.UsernameAttribute is configured.

The ways SAML.UniqueIDAttribute and SAML.NameIDFormat are configured to identify users in RStudio Connect are detailed above.

Note: The value obtained from SAML.UniqueIDAttribute 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.

Automatic Group Provisioning

In addition to delegating group membership management to the IdP, RStudio Connect can also delegate the management of groups themselves to the IdP. By using SAML.GroupsAutoProvision RStudio Connect will automatically create and optionally remove groups based on the list of group names received from the IdP.

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.

Note: RStudio Connect can be configured to automatically decommission (remove) groups without members with the additional setting SAML.GroupsAutoRemoval. It also removes the group from all content it has been previously associated with.

In this mode, it is assumed that all group management will be done externally to RStudio Connect and therefore the user interface for group management will be hidden in the Connect dashboard.

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 the alter command using the --new-owner or --drop-owner switches.

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.

Note: When both auto provisioning and auto removal are enabled, any existing groups whose names do not match the ones sent by SAML cannot be removed. The Connect Server API or the CLI should be used to remove these extra groups.

Assigning User Roles Automatically

You can configure RStudio Connect to automatically define user roles based on attributes on the SAML assertion. In the simplest configuration, the option SAML.RoleAttribute refers to an assertion attribute containing one of the values viewer, publisher or administrator.

This role attribute is not part of the SAML attribute profiles and it should be configured separately with a value that fits your organization's notion of a role for RStudio Connect users.

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

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 group names to valid user roles in RStudio Connect.

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

Metadata Configuration Example

Here is a complete SAML configuration as an example. It tells RStudio Connect to communicate to an IdP by retrieving its metadata from the given URL. Single sign-ons can be initiated by either party. The IdP will use the persistent NameID format. The user fields will be mapped from the assertion attributes as defined in the default profile. In that profile, the Unique ID will be the name ID from the IdP.

; /etc/rstudio-connect/rstudio-connect.gcfg
IdPMetaDataURL =
IdPAttributeProfile = default

You can also configure the use of metadata with individual user attribute names. This example is equivalent to the one above.

; /etc/rstudio-connect/rstudio-connect.gcfg
IdPMetaDataURL =
NameIDFormat = persistent
UsernameAttribute = "Username"
FirstnameAttribute = "FirstName"        
LastnameAttribute = "LastName"      
EmailAttribute = "Email"

Individual Settings Configuration Example

Here is a complete SAML configuration as an example but now using 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 (shortened for brevity) is a raw Base64 value, while the encryption key and certificate are paths to PEM files and because transient is being used the UniqueIDAttribute is something other than the NameID.

; /etc/rstudio-connect/rstudio-connect.gcfg
SSOInitiated = IdP
IdPEntityID =
IdPSingleSignOnServiceURL =
IdPSigningCertificate = MIADHIUfdhfkhkdshkf454sdfe5e64fF45FF5456456d4d65 ... fd378==
SPEncryptionKey = /path/to/rsa.key
SPEncryptionCertificate = /path/to/pem.cer
NameIDFormat = transient
UniqueIDAttribute = "GUID"
UsernameAttribute = "Username"
FirstnameAttribute = "FirstName"
LastnameAttribute = "LastName"
EmailAttribute = "Email"
GroupsAttribute = "Groups"

Service Provider Configuration for the IdP

Though the number of available IdPs is large and each one has its own configuration process, there are some common things to know.

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. See the following 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__/saml for RStudio Connect, replacing hostname and port as appropriate. These should match what is specified in the Server.Address configuration option.

    Note: 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 if it's a URL.

  • Assertion Consumption Service -- This is a URL in the service provider where the IdP will post authentication responses. 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/acs for RStudio Connect, replacing hostname and port as appropriate. These should match what is specified in the Server.Address configuration option.

    Note: 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 name format specification.

    Each name is the string by which its value will be known in authentication responses and must match the values specified in the SAML.UsernameAttribute, SAML.FirstNameAttribute, SAML.LastNameAttribute and SAML.EmailAttribute configuration options. The matching of these names is case sensitive.

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 Server.Address 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 SAML.SSOFollowHTTPHeaders 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.<:port>/some/path/).

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-Proto, X-Forwarded-Host, and X-Forwarded-Port are used in a "best effort" attempt to determine the original request URL.

The X-Forwarded headers are not appropriate when the proxy performs path rewriting (e.g. serving beneath Use X-RSC-Request when path-rewriting. X-RSC-Request takes precedence when both 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 (http or https) will be selected based on whether or not TLS/SSL is configured and used for the authentication attempt.

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

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