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
setting has a value of
; /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
The issuer must be an HTTPS URL and the location of the
discovery metadata for OpenID Connect.
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
In the example above the metadata URL would be
When attempting to troubleshoot a problem relating to OAuth2, you can enable
more verbose logging with
; /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
Origin URL: Use your RStudio Server URL (i.e.
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.
We recommend using a distinct set of credentials for each application you configure to use with OpenID Connect.
Visit the Google Developers Console and create a new project. Give it a name of your choosing, such as "rsconnect".
In the left navigation window, click on "Credentials", then goto the "OAuth consent screen" tab, fill in the information requested and click "Save".
Once again, click "Credentials" in the left navigation window. Then click the dropdown button "New credentials", then "OAuth client ID".
For "Application Type", select "Web Application". Then give your client ID a descriptive name.
For "Authorized redirect URIs", use your RStudio Connect server address with the path
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>
ClientSecretFile can be encrypted to avoid leakage
of the credential. See the Property
Types configuration appendix for details.
RStudio Connect will rely on the value of the claim configured in
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.
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.
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
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.
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
When using Google, enabling the
configuration option will cause the authentication to always fail. In this
case, you must customize the
configuration option to use any other claim returned by Google as the user's
"name"). In this scenario, usernames will be defined
remotely being no longer manually editable in RStudio Connect.
RStudio Connect allows users to search for other users only if authenticating with Google. This functionality is not provided by other OpenID Connect vendors.
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
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
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.
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.
Verify that you can use your OpenID Connect account to sign into 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
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.
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
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.
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
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
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,
; /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.
If the groups claim is not present, there will be no changes to existing group memberships a user may have.
Automatic Group Provisioning¶
In addition to delegating group membership management to OpenID, RStudio
Connect can also automate the management of groups themselves. By using
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.
RStudio Connect can be configured to automatically decommission (remove)
groups without members with the additional configuration option
It also removes the group from all content it has been previously associated
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
alter command using the
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.
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
Invalid role values are defaulted to the value of
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.
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.
RStudio Connect support for OpenID Connect relies on the standard OpenID Connect
Some vendors will have an effect on the scopes available by default:
- When using Okta, the
groupsscope 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
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 returning JWT (JSON Web Token)
IDToken payload or the
endpoint are 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.
groups(optional) - This will be the group memberships in RStudio Connect. Configurable via the option
OAuth2.GroupsClaimand it is optional. RStudio Connect will leave the user's group memberships untouched 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 neither the OAuth2
AccessToken or the OpenID
IDToken JWT are made available to any content which may want to consume it for