Okta Integration (Using OpenID Connect)#
RStudio Connect can integrate with Okta through the use of the OpenID Connect / OAuth2 Authentication provider.
Using this integration, user authentication will be provided by Okta. Group membership details may also be provided by Okta.
The OAuth2 configuration appendix contains information about each OpenID Connect / OAuth2 configuration option.
Relevant Okta documentation:
; /etc/rstudio-connect/rstudio-connect.gcfg [Authentication] Provider = "oauth2" [OAuth2] ClientId = "0ebfafe9-237f-4e38-a85b-a0e5d6c06782" ClientSecret = "2ab7be07-84fe-4569-b04a-ce8f1ebfc077" OpenIDConnectIssuer = "https://your-organization.okta.com/" RequireUsernameClaim = true ; Enable this for a better user experience, unless ; managing a large number of groups is a concern: ;GroupsAutoProvision = true ; When attempting to troubleshoot a problem relating to OAuth2, ; you can enable more verbose logging by enabling the following line ;Logging = true
Defining an OpenID Connect Issuer#
RStudio Connect requires metadata for the OpenID Connect identity provider that
it is being integrated with. This is specified through the configuration option
The issuer must be an HTTPS URL and the location of the
/.well-known/openid-configuration 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
Obtaining a Client ID and Client Secret#
In order for RStudio Connect to use OpenID Connect authentication, you will need a client ID and client secret from your vendor.
Different vendors require specific steps in order to obtain a client ID and a client secret. You will likely be asked for some information about RStudio Connect during this process, for example:
Application Type: "Web Application"
Redirect URL: Use your RStudio Connect server address with the path
Origin URL: Use your RStudio Server or RStudio Workbench URL (i.e.
Grant types: Authorization Code.
Please consult your OpenID Connect authentication provider's documentation for further information.
We recommend using a distinct set of credentials for each application you configure to use with OpenID Connect.
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.
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 via the RStudio Connect Server API.
User searches are performed against the list of users who have either logged in once before, had their account pre-provisioned by an administrator, or were created via the RStudio Connect Server API.
Searching against the remote authentication provider is not supported.
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
modified 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.
A user is uniquely identified in RStudio Connect by the attribute defined in
This defaults to the
sub (subject) claim which is a standard identifier in
Users are uniquely identified by their Unique ID claim in OpenID. If RStudio Connect is presented with a Unique ID it has never seen, it will create a new user.
The value obtained from
must match exactly the field
unique_id used for creating new users via the
Connect Server API. Once the user is created, the RStudio Connect identity
guid) should be used for subsequent API operations with that user.
Usernames are defined externally by the OpenID Connect identity provider. However, RStudio Connect imposes some additional restrictions on the usernames it supports:
- The following values are prohibited:
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. They are not guaranteed to be unique.
Duplicate usernames may have adverse affects on content that tracks the user credentials. Please refer to the Credentials for Content in the Advanced Users and Group Topics appendix for alternatives under this condition.
The RStudio Studio IDE does not support duplicate usernames when publishing to the same RStudio Connect host. However, it is unlikely that two users with the same usernames will be sharing the same IDE account or workstation.
In cases where the username claim is not present, it will be derived using the user's email address without the domain.
For security reasons editable usernames are always unique and RStudio Connect will enforce this constraint.
By default, the derived usernames are not editable. To allow users to edit
their username after logging in and enable administrators to edit all
setting can be defined as blank. Uniqueness across all usernames will be
enforced for any changes but this does allow for more "friendly" composition
of a username.
; /etc/rstudio-connect/rstudio-connect.gcfg [OAuth2] UsernameClaim = ""
Requiring a Username claim#
If your OpenID Connect identity provider 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 as this behavior 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
Editing User Attributes#
User profile fields present as OpenID claims are not editable in RStudio Connect.
A non-editable field can be forcefully updated before a login via the
usermanager CLI tool. See the User Management
By default, the first name, last name, and email address attributes are not editable as they are provided to by the OpenID Connect identity provider. If you need to change/update these attributes, update the user's profile in your OpenID Connect identity provider. 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 manage their user 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.
Editing User Roles#
User roles are only editable in RStudio Connect if Automatic User Role Mapping is not configured, and the OpenID authentication provider is not configured to send roles in as part of the user profile.
Automatic User Role Mapping#
You can configure RStudio Connect to automatically define user roles based on claims returned by your OpenID Connect identity provider during user login. This can be done with roles defined as part of the user profile or via OpenID group memberships.
Using Group Memberships#
This option does not work with Locally Managed Groups.
Use the configuration option
to enable user role mapping via groups.
When group mapping is enabled, configuration options to receive roles from
the authentication provider as part of the user profile information will be
ignored and RStudio Connect will fail to start if
is also enabled.
In the following example group names are used. Viewer mapping is purposely left
out so that the remaining of the users will be assigned the based on the option
which defaults to
; /etc/rstudio-connect/rstudio-connect.gcfg [Authorization] UserRoleGroupMapping = true PublisherRoleMapping = "Developers" AdministratorRoleMapping = "Dev-Leaders" AdministratorRoleMapping = "IT-Administrators"
When Groups By Unique ID are used, the role mapping should be based on the groups' Unique IDs instead of their names.
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#
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 RStudio Connect Server API can be used to manage these groups as well.
RStudio Connect obtains users group membership information from the claim
configured in the option
By default, RStudio Connect automatically assigns users to existing groups according to the list of group names sent by your authentication provider. For every login attempt, the list of group names received will be compared with the current memberships the user has, adding the user as a member of newly listed groups and removing the user from groups no longer listed.
The list of groups sent by the identity provider will override any memberships defined manually or via the RStudio Connect Server API. However, these operations should still be used between login attempts to keep the group memberships in sync with the IdP.
If the groups claim is not present in the authentication, there will be no changes to existing group memberships a user may have. In this situation, you may wish to use Locally Managed Groups in RStudio Connect instead.
Manual Group Provisioning#
Admins may use the "People" tab within the RStudio Connect dashboard to "add" references to OpenID managed groups. Group membership of RStudio Connect users will be tracked for only these groups and not the entire list of groups that are returned from OpenID.
This is the default behavior, and a good option when the RStudio Connect users are associated with a large number of groups, but only some of them are useful for content access control purposes.
Care should be taken when removing groups via "people" in the dashboard or via Connect Server API. Removing a group will also remove all associations between the group being removed and existing content.
Automatic Group Provisioning#
In addition to delegating group membership management to the OpenID Connect
identity provider, 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.
Removing stale or unused groups can be done via the dashboard, via the
RStudio Connect Server API, or ultimately via the
Switching Between Manual and Automatic Group Provisioning#
Groups created by automatic provisioning do not have owners while any groups created manually or via the RStudio 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.
Locally Managed Groups#
You can still use groups in RStudio Connect if you decide to not configure support for OpenID groups.
Locally managed groups have no relation with groups from OpenID.
These groups are local to RStudio Connect, they can be created via the Dashboard or via the Connect Server API. Group memberships must also be managed using the same means.
OAuth2.GroupsClaim to an
empty value to disable OpenID groups and use only locally managed groups.
Matching Groups' Identifiers#
By default, RStudio Connect will match the list of groups send by the OpenID Connect authentication provider against the names of the groups that exist in RStudio Connect. Some OpenID Connect providers do not send group names, and instead send unique identifiers (e.g. GUIDs).
Groups by Name#
When your OpenID Connect authentication provider sends group names, the default behavior of RStudio Connect to match groups using a case-sensitive string comparison can be used.
If groups are renamed within your OpenID Connect authentication provider,
they will be recognized as new groups. Depending on the setting for
OAuth2.GroupsAutoProvision, these new groups will either be added or
ignored. In no circumstances will the old group be renamed or removed from
You can still rename a group in RStudio Connect to match the group name in
OpenID to preserve all associations with content. If a duplicate group with the
same name was created by auto-provision, this new group must be removed first.
Groups by Unique ID#
To support the scenario where your OpenID Connect authentication provider sends
unique identifiers for groups rather than their names, RStudio Connect can be
configured to match these identifiers by using the setting
This is considered to be an advanced feature in RStudio Connect. Identifying groups by an identifier other than their name requires the use of the RStudio Connect Server API for all group management workflows. The RStudio Connect Dashboard does not allow group management in this scenario, except by the association of the group with some content, which is still possible.
A group identified by a unique identifier must be provisioned within RStudio
Connect using the RStudio Connect Server API. The API call allows for the
association of the group's
unique_id (same one sent by the OpenID Connect
authentication provider during authentication) with a locally managed,
user-friendly name, in general the same name as used in OpenID. RStudio Connect
will not enforce unique group names in this condition.
Duplicate group names may have adverse affects on content that tracks the user credentials. Please refer to the Credentials for Content in the Advanced Users and Group Topics appendix for alternatives under this condition.
OAuth2.GroupsByUniqueId is enabled,
OAuth2.GroupsAutoProvision can NOT
be enabled. This would lead to the creation of groups without meaningful names
in RStudio Connect given that OpenID would only be providing a Unique ID.
Switching Between Group Identities#
GroupsByUniqueId should be enabled before you have any groups in
RStudio Connect. If any groups have already been created, and you wish to use
this option, it is strongly recommended to run the
usermanager --groups --normalize-ids
command to make these existing groups functional under the new setting. See the
User Management CLI appendix to learn more.
usermanager command above should also be run if you decide to disable
GroupsByUniqueId in a later time.
Additional Group Options#
In the event that a claim cannot present groups as a list of distinct values,
you may use the
setting 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 = "|"
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 OpenID scopes and claims. RStudio Connect offers some options that allow adjusting these values to match your OpenID Connect authentication service provider.
RStudio Connect support for OpenID Connect relies on the standard OpenID Connect
- When using Okta, the
groupsscope is automatically added.
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
UserInfo 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