Skip to content

OpenID Connect (OAuth2)

OpenID Connect is an authentication scheme based on OAuth2 and may be used to authenticate against various vendors such as Google, Microsoft (Azure), Okta, OneLogin, Auth0, PingIdentity and many others that implement this standard.

RStudio Connect will use OpenID Connect authentication if the Authentication.Provider setting has a value of oauth2.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authentication]
Provider = oauth2

The OAuth2 configuration appendix contains information about each OpenID Connect configuration option.

By default, RStudio Connect comes pre-configured to use Google as the identity provider for OpenID Connect.

To use a provider other than Google, an OpenID Connect issuer must be defined on OAuth2.OpenIDConnectIssuer. The issuer must be an HTTPS URL and the location of the /.well-known/openid-configuration discovery metadata for OpenID Connect.

Note

The HTTPS certificate associated with the issuer URL must be valid and associated with a valid certificate authority. Self-signed certificates will not be accepted.

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
OpenIDConnectIssuer = https://openid.example.com

Note

In the example above the metadata URL would be https://openid.example.com/.well-known/openid-configuration

When attempting to troubleshoot a problem relating to OAuth2, you can enable more verbose logging with OAuth2.Logging:

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
Logging = true

In order for RStudio Connect to use OpenID Connect authentication, you will need a client ID and client secret.

Obtaining a Client ID and Client Secret

Different vendors require specific steps in order to obtain a client ID and a client secret. Most likely you will be asked for some information about RStudio Connect during this process, for example:

  • Redirect URL: Use your RStudio Connect server address with the path /__login__/callback (i.e. https://HOST:PORT/__login__/callback).

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

  • Grant types: Authorization Code.

As an example, the following instructions for obtaining an OAuth2 client ID and client secret assume you are using Google as your vendor. Please consult your OpenID Connect vendor for the appropriate steps.

Note

We recommend using a distinct set of credentials for each application you configure to use with OpenID Connect.

  1. Visit the Google Developers Console and create a new project. Give it a name of your choosing, such as "rsconnect".

  2. In the left navigation window, click on "Credentials", then goto the "OAuth consent screen" tab, fill in the information requested and click "Save".

  3. Once again, click "Credentials" in the left navigation window. Then click the dropdown button "New credentials", then "OAuth client ID".

  4. For "Application Type", select "Web Application". Then give your client ID a descriptive name.

  5. For "Authorized JavaScript origins", enter your RStudio Server URL.

  6. For "Authorized redirect URIs", use your RStudio Connect server address with the path /__login__/callback.

  7. Click "Create". Your client ID and client secret will be shown to you.

Add the client ID and secret to your configuration file as shown in the example below.

; /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 account to sign into RStudio Connect.

Note

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

Usernames

RStudio Connect will rely on the value of the claim configured in OAuth2.UsernameClaim to obtain a username. By default, RStudio Connect assumes that this claim will be present, making the username controlled by the authentication provider and therefore not editable.

Note

Usernames controlled by the authentication provider are not necessarily unique. RStudio Connect will not enforce uniqueness of usernames.

In cases where the username claim is not present, it will be derived using the user's email address without the domain.

Note

When using Google, the derived usernames are editable. Users are allowed to modify usernames after the first login. An administrator is always able to modify usernames. If you want usernames to be editable with OpenID Connect vendors other than Google, the OAuth2.UsernameClaim setting must be defined as blank.

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
UsernameClaim = ""

The process of generating an initial username from an email is limited to what is considered a valid username in RStudio Connect. For example, certain characters such as dashes (-) are replaced with underscores (_), shorter names are also padded with underscores. Resulting usernames longer than 64 characters are truncated as necessary and prohibited or duplicate usernames get an incremental suffix.

Note

For security reasons editable usernames are always unique and RStudio Connect will enforce this constraint.

Requiring a Username claim

If your OpenID Connect vendor is expected to always return a username claim, it is strongly recommended that RStudio Connect enforce the presence of the claim. That ensures RStudio Connect will never fallback to derive usernames from email addresses a behavior that has the potential to mask configuration issues with the authentication provider or RStudio Connect itself.

The setting OAuth2.RequireUsernameClaim can be used for this purpose and RStudio Connect will fail to authenticate users without a username claim if this setting is enabled.

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
RequireUsernameClaim = true

Note

When using Google, enabling the OAuth2.RequireUsernameClaim configuration option will cause the authentication to always fail. In this case, you must customize the OAuth2.UsernameClaim configuration option to use any other claim returned by Google as the user's username (i.e. "name"). In this scenario, usernames will be defined remotely being no longer manually editable in RStudio Connect.

Searches

RStudio Connect allows users to search for other users only if authenticating with Google. This functionality is not provided by other OpenID Connect vendors.

Note

When using Google for authentication, a user can be created ahead of their first login in RStudio Connect by using search within the Access Settings for a piece of content to proactively add them as a viewer or a collaborator.

That search is 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, they will become discoverable.

For OpenID Connect vendors other than Google, only local search is available. Local search means that the search results will only return users that have logged in once before, or that were created via the Connect Server API.

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

This is especially recommended if your vendor is Google. Other OpenID Connect vendors will have their own means to enforce which accounts can access RStudio Connect.

Note

Verify that you can use your OpenID Connect account to sign into 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.

Groups

Groups are supported when using OpenID Connect authentication. They can either be managed manually in the Dashboard or be automatically provisioned by the authentication provider. In both scenarios the Connect Server API can be used to manage these groups as well.

Note

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.

RStudio Connect will obtain the user's group membership information from the claim configured in the option OAuth2.GroupsClaim.

RStudio Connect will automatically assign users to existing groups when the authentication includes the claim configured in OAuth2.GroupsClaim with group membership information. This is expected to be in the form of a list of all groups, by name, that the user belongs to.

Note

Your OpenID Connect vendor may send the groups' identifiers instead of their names during login. This is true for Azure. In this situation, you should use the OAuth2.GroupsByUniqueId configuration option and manage your groups via the Connect Server API. This option also alters the values expected for role assignment via groups.

In the event that a claim cannot present groups as a list of distinct values, you can use the OAuth2.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:

; /etc/rstudio-connect/rstudio-connect.gcfg
[OAuth2]
GroupsSeparator = "|"

If the groups claim is present, RStudio Connect will adjust the group memberships of the user logging in to match the list provided in the claim, adding the user to named groups when necessary and removing them from groups that are no longer listed.

Note

If the groups claim is not present, there will be no changes to existing group memberships a user may have.

If you do not want groups at all, set the Authorization.UserGroups configuration option to false and force OAuth2.GroupsClaim to an empty value.

Automatic Group Provisioning

In addition to delegating group membership management to OpenID, RStudio Connect can also automate the management of groups themselves. By using OAuth2.GroupsAutoProvision RStudio Connect will automatically create and optionally remove groups based on the list of group names received from the OpenID Connect groups claim.

With this option enabled, groups are provisioned in RStudio Connect when the first member is added and remain there indefinitely, even after the last member has been removed, so that any access to content is preserved for a future member of those groups.

Note

RStudio Connect can be configured to automatically decommission (remove) groups without members with the additional configuration option OAuth2.GroupsAutoRemoval. It also removes the group from all content it has been previously associated with.

In this mode, it is assumed that all group management will be done externally to RStudio Connect and therefore the user interface for group management will be hidden in the Connect dashboard.

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.

RStudio Connect will issue a warning on startup if the ownership of the existing groups does not match your current configuration for group provisioning.

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.

Any groups that had been automatically provisioned should be assigned an owner if you intend to manage them in RStudio 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. This can be done via the Connect dashboard, the Connect Server API or the usermanager. See the User Management CLI appendix to learn more.

Note

When both auto provisioning and auto removal are enabled, any existing groups which the names do not match the ones sent by OpenID cannot be removed. The Connect Server API or the CLI should be used to remove these extra groups.

Assigning User Roles Automatically

You can configure RStudio Connect to automatically define user roles based on claims returned by OpenID Connect. 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 and the issue is reported in the logs if debug logging is enabled.

If you prefer to map the values of a field to RStudio Connect user roles, you can use the Automatic User Role Mapping to map custom values returned during authentication or group names to valid user roles in RStudio Connect.

Note

Roles are no longer editable via the Dashboard if assigned automatically.

Customizing OpenID Connect

The RStudio Connect default configuration relies on standard OpenID Connect values for authentication. However, some vendors may use other proprietary values. This is especially true for OpenID scopes and claims. RStudio Connect offers some options that allow adjusting these values to match your OpenID Connect vendor.

Customizing Scopes

RStudio Connect support for OpenID Connect relies on the standard OpenID Connect scopes openid, email and profile.

Note

Some vendors will have an effect on the scopes available by default:

  • When using Okta, the groups scope is automatically added.
  • 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 returning JWT (JSON Web Token) IDToken payload or the UserInfo endpoint are 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.

  • groups (optional) - This will be the group memberships in RStudio Connect. Configurable via the option OAuth2.GroupsClaim and it is optional. RStudio Connect will leave the user's group memberships untouched 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 neither the OAuth2 AccessToken or the OpenID IDToken JWT are made available to any content which may want to consume it for security purposes.