Google Integration (Using OpenID Connect)

Posit 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 Posit 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 troubleshooting an OAuth2 problem, more verbose logging
; is produced by uncommenting the following line:
;Logging = true

Configuration

Obtaining a Client ID and Client Secret

In order for Posit 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 Posit Connect during this process, for example:

  • Application Type: “Web Application”

  • Authorized redirect URIs: Use your Posit Connect server address with the path /__login__/callback (i.e. https://HOST:PORT/__login__/callback).

  • Authorized JavaScript origins: Use your RStudio Server or Posit Workbench 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 Posit 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 Posit 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 Posit Connect dashboard or by using the Posit Connect Server API.

User Discoverability

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

Posit 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 Posit Connect account via a login attempt, they will become discoverable.

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

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 Posit 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 Posit Connect on the next user login.

Note

Forcing the claims for first name, last name or email to blank values in the Posit 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 Posit 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 Posit 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 Posit 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 Posit 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 Posit Connect Server API.

Restricting User Access

The default configuration allows all account holders to access Posit 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 Posit Connect before attempting to configure access restrictions.

The OAuth2.AllowedDomain setting specifies the set of domains that are allowed to access your Posit 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 Posit 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 Posit 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. Posit Connect offers some options that allow adjusting these values to match your OAuth2 authentication service provider.

Customizing Scopes

Posit 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 Posit Connect. Configurable via the option OAuth2.UniqueIdClaim.

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

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

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

  • preferred_username (optional) - This will be the user’s username in Posit Connect. Configurable via the option OAuth2.UsernameClaim and it is optional unless OAuth2.RequireUsernameClaim is enabled. Posit 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 Posit Connect side and pre-existing values will be left untouched. To make a particular user profile field manually editable in Posit 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.