Skip to content

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#

Note

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

Important

Though it is not typically required, the Server.Address 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

Tip

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.

Configuration#

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.

Notes#

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

    Warning

    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.

    Note

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

    Warning

    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.

    Tip

    If you are using the IdPAttributeProfile as 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 IdPAttributeProfile is 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 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.

Warning

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.

Note

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

Important

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.

For example,

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

Warning

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.

Important

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

Except for SAML.IdPSigningCertificate, if you use the individual 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.

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:

Important

RStudio Connect supports at least a subset of SAML called Interoperable SAML.

Notably, certain functionalities are currently absent:

  • Single Logout

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

Supporting Signed Authentication Requests#

Note

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

Note

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.

Use the SAML.SPSigningKey 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 SAML.SPSigningCertificate to provide the public certificate to RStudio Connect. Do this to include the certificate in the SP metadata that RStudio Connect will produce.

Warning

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 sha1, sha256 and sha512. Your choice needs to be configured in the SAML.SPRequestSigningMethod option. When in doubt, try sha256 first which offers a good balance between security and compatibility.

Note

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

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.

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.

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.

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

Note

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.

There are two ways to tell RStudio Connect about how this data is mapped, Using Attribute Profiles, which is preferred, or Specifying Attributes Yourself.

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

The default Profile#

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

Important

The attribute profiles never define a SAML.RoleAttribute 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#

Important

The matching of the SAML attribute names is case sensitive in RStudio Connect.

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.

Note

The setting SAML.IdPAttributeProfile will override the individual attribute settings. Make sure this setting is not defined.

Generated Usernames#

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 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 SAML.UsernameAttribute should be forced to have a blank value ("") and the header which contains the user's email must be configured in the setting SAML.EmailAttribute.

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.

Note

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 usermanager CLI tool before restarting RStudio Connect with the new configuration. See the User Management CLI appendix for more information.

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

User Provisioning#

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 Authorization.DefaultUserRole 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#

SAML.RegisterOnFirstLogin can be used to disable the registration through login behavior.

; /etc/rstudio-connect/rstudio-connect.gcfg
[SAML]
RegisterOnFirstLogin = false

Important

Using this option requires users to be exclusively created via the RStudio Connect Server API.

Usernames#

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: connect, apps, users, groups, setpassword, user-completion, confirm, recent, reports, plots, unpublished, settings, metrics, tokens, help, login, welcome, register, resetpassword, content

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

Tip

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.

Note

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.

Unique ID#

In addition to the value specified for NameIDFormat (as described above), 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.

Warning

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.

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.

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.

Note

A non-editable field can be forcefully updated before a login via the usermanager CLI tool. See the User Management CLI appendix.

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.

For fields with no attribute mapping, the Authorization.UserInfoEditableBy 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 Authorization.UserInfoEditableBy with Admin if profile editing should be restricted to administrators.

Tip

It is recommended that if you disable SAML.RegisterOnFirstLogin with a value of false, that you also configure Authorization.UserInfoEditableBy to 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 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 SAML group memberships.

Using Group Memberships#

Important

This option does not work with Locally Managed Groups.

Use the configuration option Authorization.UserRoleGroupMapping to enable user role mapping via groups.

Warning

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

is also enabled.

When enabled, the configuration options Authorization.ViewerRoleMapping, Authorization.PublisherRoleMapping, and Authorization.ViewerRoleMapping will refer to groups.

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 Authorization.DefaultUserRole which defaults to viewer.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authorization]
UserRoleGroupMapping = true
PublisherRoleMapping = "Developers"
AdministratorRoleMapping = "Dev-Leaders"
AdministratorRoleMapping = "IT-Administrators"

Note

When Groups By Unique ID are used, the role mapping should be based on the groups' Unique IDs instead of their names.

Using User Profile Roles#

You can configure RStudio Connect to automatically define user roles based on attributes on the SAML assertion.

Use the configuration option Authorization.UserRoleMapping to enable user role mapping.

The SAML.RoleAttribute configuration option should also be defined to receive role information as part of the user profile.

Note

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 viewer, publisher and administrator to define roles in RStudio Connect.

The 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 configuration options Authorization.ViewerRoleMapping, Authorization.PublisherRoleMapping, and Authorization.AdministratorRoleMapping.

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.

Note

If there are concerns about security, a more restrictive behavior can be used in these scenarios with the configuration option Authorization.UserRoleMappingRestrictive. 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.

Use the setting SAML.GroupsAttribute or select a SAML IdP profile SAML.IdPAttributeProfile which will define this setting automatically.

Note

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.

Tip

If you don't wish to use the groups sent by your IdP, you can use the configuration option SAML.IdPAttributeProfileGroups with a value of false to disable group support when using a SAML.IdPAttributeProfile. The setting SAML.GroupsAttribute must also be left undefined. In this case, it is still possible to use Locally Managed Groups in RStudio Connect.

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.

Tip

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.

Warning

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

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.

Tip

Removing stale or unused groups can be done via the dashboard, via the RStudio Connect Server API, or ultimately via the usermanager CLI.

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.

Locally Managed Groups#

You can still use groups in RStudio Connect if you decide to not configure support for SAML groups.

Important

Locally managed groups have no relation with groups on your IdP.

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.

Tip

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

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.

Important

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

Warning

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.

Tip

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.

Important

When 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#

Preferably, 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. The 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 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. https://connect.proxy.company.com<: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 https://proxy.company.com/rsc/). 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.

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 UniqueIDAttribute is something other than the NameID.

; /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"
Copyright © RStudio, PBC. All Rights Reserved