Skip to content

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.

Configuration Example

Note

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

Configuration

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 /__login__/callback (i.e. https://HOST:PORT/__login__/callback).

  • Authorized JavaScript origins: Use your RStudio Server URL (i.e. https://HOST:PORT).

  • Grant types: Authorization Code.

Note

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

With OAuth2.ClientId and either OAuth2.ClientSecret or OAuth2.ClientSecretFile configured, you can use your Google account to sign in to RStudio Connect.

Note

The ClientSecret or ClientSecretFile can be encrypted to avoid leakage of the credential. See the Property Types configuration appendix for details.

User Provisioning

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.

User Discoverability

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

If you wish to disable this feature, set the configuration setting OAuth2.RegisterOnFirstLogin to false.

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

Important

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

Usernames

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

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.

Note

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.

The setting Authorization.UserInfoEditableBy controls whether your users will be permitted to make changes to their profile attributes. The setting Authorization.UserInfoEditableBy 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.

Tip

It is recommended that if you disable OAuth2.RegisterOnFirstLogin, that you also configure Authorization.UserInfoEditableBy to Admin.

Automatic User Role Mapping

You may configure RStudio Connect to automatically define users roles based on claims returned by Google during user login.

Note

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 Authorization.UserRoleMapping to enable user role mapping.

The OAuth2.RoleClaim 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 viewer, publisher or administrator.

Note

Invalid role values are defaulted to the value of Authorization.DefaultUserRole.

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:

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.

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"

Note

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.

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.

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.

Note

Verify that you can use your Google credentials to sign in to RStudio Connect before attempting to configure access restrictions.

The OAuth2.AllowedDomain 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 insufficient. The OAuth2.AllowedEmail 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 = "jdoe@company.com"
AllowedEmail = "asmith@subsidiary.com"

It is important to understand how the OAuth2.AllowedDomain and OAuth2.AllowedEmail properties interact.

If only OAuth2.AllowedDomain is configured, only email addresses with a listed domain will be permitted access.

If only OAuth2.AllowedEmail is configured, only listed email addresses will be permitted access.

When both OAuth2.AllowedDomain and OAuth2.AllowedEmail are specified, email addresses given in OAuth2.AllowedEmail are permitted access in addition to email addresses with a domain listed in OAuth2.AllowedDomain.

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.

Customizing Scopes

RStudio Connect support for OpenID Connect relies on the standard OpenID Connect scopes openid, email and 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 OAuth2.CustomScope. You should define one additional scope per line. For example:

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
CustomScope = "my_custom_scope1"
CustomScope = "my_custom_scope2"

Note

Custom scopes are generally expected by the authentication provider in order to return non-standard claims.

Customizing 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 OAuth2.UniqueIdClaim.

  • email - This will be the email and the derived username in RStudio Connect. Configurable via the option OAuth2.EmailClaim.

  • given_name - This will be the user's first name in RStudio Connect. Configurable via the option OAuth2.FirstNameClaim.

  • family_name - This will be the user's last name in RStudio Connect. Configurable via the option OAuth2.LastNameClaim.

  • preferred_username (optional) - This will be the user's username in RStudio Connect. Configurable via the option OAuth2.UsernameClaim and it is optional unless OAuth2.RequireUsernameClaim is enabled. RStudio Connect will derive the username during the first login from the user's email address if not present or blank.

Note

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

Known Limitations

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.