Google Integration (Using OpenID Connect)#
RStudio Connect can integrate with Google through the use of the OpenID Connect / OAuth2 Authentication provider.
Using this integration, user authentication will be provided by Google. Group functionality is provided by RStudio Connect and is independent of Google.
The OAuth2 configuration appendix contains information about each OAuth2 and OpenID Connect configuration options.
Relevant Google documentation:
; /etc/rstudio-connect/rstudio-connect.gcfg [Authentication] Provider = "oauth2" [OAuth2] ClientId = "client-google" ClientSecret = "2ab7be07-84fe-4569-b04a-ce8f1ebfc077" AllowedDomain = "company.com" ; When attempting to troubleshoot a problem relating to OAuth2, ; you can enable more verbose logging by enabling the following line ;Logging = true
Obtaining a Client ID and Client Secret#
In order for RStudio Connect to integrate with Google, you will need to obtain a client ID and client secret from Google. Refer to the Google documentation for setting up OAuth 2.0.
Most likely you will be asked for some information about RStudio Connect during this process, for example:
Application Type: "Web Application"
Authorized redirect URIs: Use your RStudio Connect server address with the path
Grant types: Authorization Code.
We recommend using a distinct set of credentials for each application you configure to use with Google
; /etc/rstudio-connect/rstudio-connect.gcfg [OAuth2] ClientId = "<CLIENT ID>" ClientSecret = "<CLIENT SECRET>"
ClientSecretFile can be encrypted to avoid leakage
of the credential. See the Property
Types configuration appendix for details.
Users are created in RStudio Connect upon their first successful login attempt. Users may also be created ahead of their first login by adding them as users within the "People" tab of the RStudio Connect dashboard or by using the RStudio Connect Server API.
RStudio Connect allows users to search for other users using the Google Directory API. These searches are performed on behalf of the current user. Different accounts may have different visibility within the user directory and therefore will see different results. This is most obvious when you have configured RStudio Connect to allow access to two different domains. Users in company.com, for example, will likely not be able to search for colleagues in subsidiary.com.
RStudio Connect augments the Google Apps user directory search with a local search across its set of known accounts. Once your colleague has created their own RStudio Connect account via a login attempt, they will become discoverable.
Register on First Login#
By default, users can be created in RStudio Connect upon their first successful
login attempt. Accounts will be created with the role specified in the
setting (see User Roles) or via User
Role Mapping if configured. Otherwise, the role may be
specified as the user is manually added within the dashboard or via the RStudio
Connect Server API.
Disabling Register on First Login#
If you wish to disable this feature, set the configuration setting
; /etc/rstudio-connect/rstudio-connect.gcfg [OAuth2] RegisterOnFirstLogin = false
Using this option requires users to be exclusively created via the RStudio Connect Server API.
As Google does not provide usernames, they are automatically derived using the user's email address without the domain.
Users are allowed to modify usernames after their first login. An administrator is always able to modify usernames.
Usernames must be unique and adhere to the following:
- Be 3-64 characters in length
- Start with a letter
- Contain only alphanumeric characters, underscores, and periods
- Some values are prohibited:
Editing User Attributes#
By default, the first name, last name, and email address attributes are not editable as they are provided by Google. If you need to change/update these attributes, update the user's profile in Google. The changes will be synced into RStudio Connect on the next user login.
Forcing the claims for first name, last name or email to blank values in the RStudio Connect configuration will make these fields editable, and they will no longer be updated every login.
controls whether your users will be permitted to make changes to their profile
attributes. The setting
has a default value of
AdminAndSelf, permitting users and administrators to
manage these user profile attributes. A value of
Admin permits only
administrators to make changes to a user's profile.
Automatic User Role Mapping#
You may configure RStudio Connect to automatically define users roles based on claims returned by Google during user login.
This will require a custom claim to be configured in Google, and is only possible with Google Apps domains.
Using User Profile Roles#
Use the configuration option
to enable user role mapping.
configuration option should also be defined to receive role information as part
of the user profile.
In the simplest configuration, the option
OAuth2.RoleClaim refers to a
claim containing one of the values
Invalid role values are defaulted to the value of
If you prefer to map custom values returned during authentication or group names to valid user roles in RStudio Connect, you may use the following settings:
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
administrator to define roles in RStudio
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"
Roles will no longer be editable via the Dashboard if assigned automatically.
Multiple User Role Mappings#
When there are multiple matches between the configured mapping and the user or group information sent by the authentication provider, the role with the most privileges is selected. This behavior makes it easy to promote users to a new role.
If there are concerns about security, a more restrictive behavior can be
used in these scenarios with the configuration option
When enabled, it will cause the least privileged role to be selected.
Group Membership Management#
When using Google for authentication, groups are local to RStudio Connect and have no relation to any organization groups present in Google Apps, for example.
They can either be managed manually in the Dashboard or via the RStudio Connect Server API.
Restricting User Access#
The default configuration allows all account holders to access RStudio Connect. You may want to limit access to specific domains that are used by your organization.
Verify that you can use your Google credentials to sign in to RStudio Connect before attempting to configure access restrictions.
setting specifies the set of domains that are allowed to access your RStudio
Connect server. Multiple domains should be entered one per line.
; /etc/rstudio-connect/rstudio-connect.gcfg [OAuth2] AllowedDomain = "company.com" AllowedDomain = "subsidiary.com"
You may also restrict access by email address if using domain alone is
setting specifies the set of email addresses that are allowed to access your
RStudio Connect server. Multiple addresses should be entered one per line.
; /etc/rstudio-connect/rstudio-connect.gcfg [OAuth2] AllowedEmail = "firstname.lastname@example.org" AllowedEmail = "email@example.com"
It is important to understand how the
OAuth2.AllowedEmail properties interact.
OAuth2.AllowedDomain is configured, only email addresses with a
listed domain will be permitted access.
OAuth2.AllowedEmail is configured, only listed email addresses will
be permitted access.
OAuth2.AllowedEmail are specified, email
addresses given in
OAuth2.AllowedEmail are permitted access in addition to
email addresses with a domain listed in
Advanced Configuration Notes#
Customizing OpenID Connect#
The RStudio Connect default configuration relies on standard OpenID Connect values for authentication. However, some vendors may use proprietary values. This is especially true for OAuth2 scopes and claims. RStudio Connect offers some options that allow adjusting these values to match your OAuth2 authentication service provider.
RStudio Connect support for OpenID Connect relies on the standard OpenID Connect
profile. When using Google, an additional scope
is included for access to Google Directory in support of user search.
You can include additional scopes if necessary by using the configuration option
should define one additional scope per line. For example:
; /etc/rstudio-connect/rstudio-connect.gcfg [OAuth2] CustomScope = "my_custom_scope1" CustomScope = "my_custom_scope2"
Custom scopes are generally expected by the authentication provider in order to return non-standard claims.
By default, the
UserInfo endpoint is expected to return the following claims:
sub- This will be user unique identifier (UniqueID) in RStudio Connect. Configurable via the option
given_name- This will be the user's first name in RStudio Connect. Configurable via the option
family_name- This will be the user's last name in RStudio Connect. Configurable via the option
preferred_username(optional) - This will be the user's username in RStudio Connect. Configurable via the option
OAuth2.UsernameClaimand it is optional unless
OAuth2.RequireUsernameClaimis enabled. RStudio Connect will derive the username during the first login from the user's email address if not present or blank.
Defined claims that return blank user profile fields cannot be edited in RStudio Connect side and pre-existing values will be left untouched. To make a particular user profile field manually editable in RStudio Connect you should set the respective configuration option for the claim to blank. In the following example, the first and last names are editable in the Dashboard:
; /etc/rstudio-connect/rstudio-connect.gcfg [OAuth2] FirstNameClaim = "" LastNameClaim = ""
It's important to understand that the OAuth2
AccessToken is not made
available to any content which may want to consume it for security purposes.