Skip to content

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.

Configuration Example#

Note

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

Configuration#

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

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

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

  • Grant types: Authorization Code.

Please consult your OpenID Connect authentication provider's documentation for further information.

Note

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

With OAuth2.ClientId and either OAuth2.ClientSecret or OAuth2.ClientSecretFile configured, you can use your 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 via the RStudio Connect Server API.

User Discoverability#

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.

Note

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 Authorization.DefaultUserRole 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 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.

Unique ID#

A user is uniquely identified in RStudio Connect by the attribute defined in OAuth2.UniqueIdClaim. This defaults to the sub (subject) claim which is a standard identifier in OpenID.

Warning

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.

Note

The value obtained from OAuth2.UniqueIdClaim 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#

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

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. They are not guaranteed to be unique.

Tip

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.

Note

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.

Generated Usernames#

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

Note

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

Note

By default, the derived usernames are not editable. To allow users to edit their username after logging in and enable administrators to edit all usernames, the OAuth2.UsernameClaim 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.

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

Editing User Attributes#

User profile fields present as OpenID claims are not editable in RStudio Connect.

Note

A non-editable field can be forcefully updated before a login via the usermanager CLI tool. See the User Management CLI appendix.

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.

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 manage their user 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.

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#

Important

This option does not work with Locally Managed Groups.

Use the configuration option Authorization.UserRoleGroupMapping to enable user role mapping via groups.

Note

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 Authorization.UserRoleMapping is also enabled.

When enabled, the configuration options Authorization.ViewerRoleMapping, Authorization.PublisherRoleMapping, and Authorization.AdministratorRoleMapping will refer to groups.

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 Authorization.DefaultUserRole which defaults to viewer.

; /etc/rstudio-connect/rstudio-connect.gcfg
[Authorization]
UserRoleGroupMapping = true
PublisherRoleMapping = "Developers"
AdministratorRoleMapping = "Dev-Leaders"
AdministratorRoleMapping = "IT-Administrators"

Note

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

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 OAuth2.GroupsClaim.

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.

Note

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.

Tip

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.

Tip

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.

Warning

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

Tip

Removing stale or unused groups can be done via the dashboard, via the RStudio Connect Server API, or ultimately via the usermanager CLI.

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

Locally Managed Groups#

You can still use groups in RStudio Connect if you decide to not configure support for OpenID groups.

Important

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.

Set OAuth2.GroupsClaim to an empty value to disable OpenID groups and use only locally managed groups.

Tip

If you do not want groups at all in RStudio Connect, set Authorization.UserGroups to false in addition to an empty OAuth2.GroupsClaim.

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.

Note

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 content ACLs. 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 OAuth2.GroupsByUniqueId.

Warning

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.

Tip

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.

Important

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

Preferably, 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. The 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 OAuth2.GroupsSeparator 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, group_1|group_2, set:

; /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.

Customizing Scopes#

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

Note

  • When using Okta, the groups scope is automatically added.

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.

Copyright © RStudio, PBC. All Rights Reserved