Authentication Integration (Using SAML)

If your company’s authentication infrastructure supports SAML, you can use the Posit Connect SAML authentication provider to integrate the two systems.

Using this integration, user authentication is done with your Identity Provider.

Other SAML integration options include:

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 = posit.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 troubleshooting a SAML problem, more verbose logging
; is produced by uncommenting the following line:
;Logging = true

Tip

In the example above, the value for IdPAttributeProfile corresponds 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 require you to manually enter information about Posit 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 Posit Connect Service Provider Configuration.

Other IdPs require you to provide a Service Provider (SP) metadata as one of the first steps of the configuration. In this situation, the Posit 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 Posit Connect. Only then can you obtain the Posit Connect Service Provider metadata.

Notes

Posit Connect supports SAML 2.0 only.
User searching in Posit Connect will only search users which have logged in or created via the Posit Connect Server API.
User group searching in Posit Connect will only search groups which have been populated from user logins or created via the Posit Connect Server API.
It is required that Posit Connect be configured to listen on a port secured with TLS to make sure SAML login assertions are posted to the Posit 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 Posit 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 Posit 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 Posit 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 Posit 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 Posit 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 Posit Connect will use.

Note

It is not required that the IdP be able to access this URL. It means that Posit 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 Posit 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 are used for them in authentication responses. They are usually specified in name/value pairs, though they may include a format specification. Posit Connect handles all formats as strings.

Each name is the string by which its value is known in authentication responses and must match the values specified in 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.

Posit Connect SAML metadata

Some IdPs can configure basic information about a service provider from its metadata file. Posit Connect will serve its SAML metadata from the https://<hostname>[:port]/__login__/saml endpoint (the same as Posit Connect’s entity ID). If the IdP accepts a URL for the SP’s metadata (and the IdP has the means to reach Posit 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 Posit Connect as follows:

curl https://localhost:3443/__login__/saml --output metadata.xml

The above assumes you are executing curl from the machine where Posit 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 Posit Connect is accessible.

Warning

Posit Connect will only be able to serve its metadata when running with minimally valid SAML configuration with the IdP information defined.

Posit Connect service provider configuration

There are two ways to configure the information Posit 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 IdP 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

Posit 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 Posit 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 Posit Connect to read the metadata from the named, locally accessible file.

Warning

The retrieved, or read, metadata is cached while Posit 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 Posit 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 Posit 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 Posit 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 Posit 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 Posit 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 Posit Connect SAML configuration in order to proceed:

Encrypted Assertions and Responses
Signed Authentication Requests
POST or Redirect Binding
Single Sign-On Initiation
Name ID Format

Important

Posit 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 Posit 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 Posit Connect. Do this to include the certificate in the SP metadata that Posit Connect will produce.

Supporting signed authentication requests

Note

All SAML responses must be signed by your IdP. This section is about whether or not Posit 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 Posit 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 Posit 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 Posit Connect. Do this to include the certificate in the SP metadata that Posit Connect will produce.

Warning

Posit 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 Posit 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 Posit Connect to use POST binding (true) or redirect binding (false, the default) when Posit Connect is to initiate a single sign-on operation with your IdP. Redirect is the most common choice.

If you use POST binding, Posit 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, Posit 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 Posit 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 Posit Connect, Posit 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 Posit 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 Posit Connect. In this mode, an IdP-initiated login will fail, since there would be no matching authentication request that Posit 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 Posit 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 Posit 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, Posit 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 Posit Connect is unspecified, any values from the IdP will be accepted.
If the value configured for Posit 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 Posit 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.

Posit Connect can automatically assign users to groups when SAML authentication assertion includes group membership information.

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

Using attribute profiles

There are times when Posit 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 Posit Connect’s database.

Use the SAML.IdPAttributeProfile configuration option to specify the profile Posit 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 Posit 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 Posit 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), Posit 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, Posit 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. Posit 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 Posit 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 Posit 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 Posit Connect.

Register on first login

By default, users can be created in Posit 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 Posit 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 Posit Connect Server API.

Usernames

Usernames are defined externally by the SAML authentication service provider.
However, Posit 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 IDE does not support duplicate usernames when publishing to the same Posit 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, Posit 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 Posit 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 Posit 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 Posit Connect.

Editing user attributes

User profile fields present in the SAML assertion are not editable in Posit 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 Posit 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 Posit 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 Posit 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

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

Warning

It is not possible to use both user profile attributes and group memberships to determine user roles. Posit Connect will not start if the configuration options for both features, Authorization.UserRoleGroupMapping and Authorization.UserRoleMapping, are set to true.

Using group memberships

Important

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 Authorization.UserRoleGroupMapping to true.

When this feature is enabled, use the configuration options Authorization.ViewerRoleMapping, Authorization.PublisherRoleMapping, and Authorization.AdministratorRoleMapping 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.

Note

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 Dev-Leaders and 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 Authorization.DefaultUserRole option, which defaults to viewer.

; /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 SAML.RoleAttribute 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 viewer, publisher and administrator, no other action is needed.

If the specified attribute does not contain the exact values viewer, publisher and administrator, you must provide the expected values. To do this, set the configuration option Authorization.UserRoleMapping to true. Then, use the configuration options Authorization.ViewerRoleMapping, Authorization.PublisherRoleMapping, and Authorization.AdministratorRoleMapping 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 HR and Marketing.

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

Note

When the role attribute received from the authentication provider does not match any of the configured values, the user retains their current Posit Connect role. New users are assigned the default role. The default role is viewer, and can be configured with Authorization.DefaultUserRole. User role mismatches are included in 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.

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

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

Manual group provisioning

Admins may use the “People” tab within the Posit Connect dashboard to “add” references to SAML managed groups. Group membership of Posit 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 Posit 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, Posit 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 Posit 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 Posit 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.

Posit 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 Posit 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 Posit Connect. These groups have no relation to groups in your IdP.

Important

If are using a SAML.IdPAttributeProfile and wish to use local groups, you must set the configuration option SAML.IdPAttributeProfileGroups to false and leave SAML.GroupsAttribute undefined.

Locally-managed groups can be created in Posit Connect’s Dashboard or via the Connect Server API. Group memberships must be managed using the same means.

Tip

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

Matching groups identifiers

By default, Posit Connect matches the list of groups send by the SAML IdP against the names of the groups that exist in Posit 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 Posit 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 Posit 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, Posit Connect can be configured to match these identifiers by using the setting SAML.GroupsByUniqueId.

Warning

This is considered to be an advanced feature in Posit Connect. Identifying groups by an identifier other than their name requires the use of the Posit Connect Server API for all group management workflows. The Posit 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 Posit 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. Posit 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 Posit 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 Posit 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, Posit 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 Posit 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"

SAML Integration Example

Configuration

Notes

Identity provider configuration

Posit Connect SAML metadata

Posit Connect service provider configuration

Using IdP metadata

Providing specifics yourself

Other SAML options

Supporting encrypted assertions and responses

Supporting signed authentication requests

SAML binding

Single Sign-On initiation

Name ID format

User attribute mapping

Using attribute profiles

The default profile

Specifying attributes yourself

Generated usernames

Additional group attribute options

User provisioning

Register on first login

Disabling register on first login

Usernames

Unique ID

Editing user attributes

Editing user roles

Automatic user role mapping

Using group memberships

Using user profile attributes

Multiple user role mappings

SAML group membership management

Manual group provisioning

Automatic group provisioning

Switching between manual and automatic group provisioning

Locally managed groups

Matching groups identifiers

Groups by name

Groups by unique ID

Switching between group identities

Authenticating with SAML using multiple network aliases

Other configuration examples

The `default` profile