The SAML protocol is an industry standard for single-sign-on, multi-factor authentication, and authorization within the enterprise. RStudio Connect supports SAML 2.0 for authentication and group membership. For the full reference on RStudio Connect’s SAML implementation, see the RStudio Connect Admin Guide.
To get started with SAML for RStudio Connect, you will need:
- RStudio Connect version 1.7.6 or later installed
- Information about your SAML Identity Provider (or access to someone who has this information)
- The URL that RStudio Connect is accessed at in users’ browsers
The process of configuring SAML will differ across implementations, so you must first know which SAML Identity Provider you intend to use. RStudio Connect will be a Service Provider (SP) to this SAML Identity Provider (IdP).
If you have problems integrating RStudio Connect with your SAML Identity Provider, please send an email to support@rstudio.com
Integrated Providers
If you use one of the following identity providers, then there are integrated templates that you can use to simplify your setup. Other providers will need to use the “General Setup” instructions below.
Each provider has a custom guide prepared to simplify the configuration process.
|
Identity Provider |
Link |
|
Azure Active Directory |
https://azuremarketplace.microsoft.com/en-us/marketplace/apps/aad.rstudioconnect?tab=Overview |
|
Okta |
https://saml-doc.okta.com/SAML_Docs/How-to-Configure-SAML-2.0-for-RStudio-Connect.html |
|
Onelogin |
|
|
JumpCloud |
NOTE: Depending on the provider, you may need to add the integration to your account before the guide is made available.
Other providers are supported through the “General Setup” instructions below.
General Setup
For all other identity providers, or to proceed with custom configuration, follow the steps below.
1. Determine your RStudio Connect “Server Address,” the URL where users will visit RStudio Connect. For explanation, we will use the example URL: https://example.com
2. Configure a Service Provider (SP) for RStudio Connect within your SAML Identity Provider (IdP). Modify our example values to fit your environment.
a. The “Entity ID” or unique URL for RStudio Connect will be directly related to your “Server Address” from step 1. Using our example: https://example.com/__login__/saml
** NOTE: this is two underscores before and two underscores after the word “login”
b. The “Assertion Consumer Response” URL for RStudio Connect will be directly related to your “Server Address” as well. Using our example:
https://example.com/__login__/saml/acs
c. The “Login URL” for RStudio Connect to create SP-initiated logins will just be your Server Address. In our example:
https://example.com
d. SAML creates an Assertion when users log into the system. Some Identity Providers will require that you configure the assertion attributes for the Service Provider. By default, RStudio Connect uses the following attributes (case sensitive). These attributes can be configured and changed if desired:
- Username
- FirstName
- LastName
e. If your Identity Provider can pass groups in an Assertion Attribute, those groups can be defined within RStudio Connect. By default, this attribute is named “Groups.” You can either configure:
- A multi-valued Assertion Attribute
- A single-valued Assertion Attribute, where multiple group memberships are text-delimited (e.g. group1|group2|group3)
f. You will need the IdP Metadata provided by your Identity Provider. Oftentimes, this is just a HTTPS URL that the XML metadata can be fetched from. Otherwise, the XML file can be downloaded and moved to the RStudio Connect server.
3. Configure RStudio Connect. We will use the values above to configure RStudio Connect. More documentation on the available options is available in the RStudio Connect Administrator Guide.
a. Ensure that the Server Address is set within the [Server] configuration block
[Server]
Address = https://example.com
b. Ensure that the Authentication method has been set to SAML
[Authentication]
Provider = saml
c. The SAML configuration section will use the values that you determined above
[SAML]
; used for debugging
Logging = true
; Important. The IdP Metadata URL or path to IdP Metadata
; on the file system. If this metadata is not available, you
; will need to provide a more advanced configuration not shown here.
IdPMetaData =
; this is defined by your Identity Provider. one of:
; persistent, transient, emailAddress, or unspecified (the default)
NameIDFormat = persistent
; the unique identifier for a user over time
UniqueIdAttribute = NameID
; attribute mapping
UsernameAttribute = Username
FirstNameAttribute = FirstName
LastNameAttribute = LastName
EmailAttribute = Email
; optional, if using groups
GroupsAttribute = Groups
; if using a single-valued, text-delimited list of groups
; for example: group1|group2|group3
; GroupsSeparator = |
d. If you want to have groups be auto-created, have membership managed by SAML, and optionally have groups auto-removed when a group has no members, then use the following setting:
[SAML]
GroupsAutoProvision = true
; optional setting to remove groups when it has no members
; GroupsAutoRemoval = true
Troubleshooting
If you have trouble getting authentication to work with RStudio Connect, it is important to ensure that the configuration above was done correctly. The SAML protocol is very strict about URLs being written correctly, attributes being case sensitive, and attributes matching.
Some useful tools in this process:
- The RStudio Connect log file (at /var/log/rstudio-connect.log by default)
- Your SAML identity provider, or the people who manage it
- Exploring the SAML assertions
It will be important to understand the type of SAML assertion that will be made by users requesting access to RStudio Connect. There are browser extensions that allow viewing these SAML assertions in some contexts, but it is best to contact those responsible for your SAML Identity Provider for an example of what to expect.
This SAML assertion has had many XML components removed, but illustrates many of the important attributes and values that RStudio Connect uses to manage user identities.
<?xml
version="1.0"
encoding="UTF-8"?>
<saml2p:Response ...>
<saml2:Assertion ...>
...
<saml2:Subject ...>
<saml2:NameID
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">julie@example.com
</saml2:NameID>
...
</saml2:Subject>
<saml2:AttributeStatement
xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
<saml2:Attribute Name="FirstName">
<saml2:AttributeValue>Julie
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="LastName">
<saml2:AttributeValue>Doe
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="Email">
<saml2:AttributeValue>julie@example.com
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="Username">
<saml2:AttributeValue>juliedoe
</saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="Groups">
<saml2:AttributeValue>Everyone
</saml2:AttributeValue>
<saml2:AttributeValue>Connect Group
</saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>
</saml2:Assertion>
</saml2p:Response>
Comments