Okta Integration (Using OpenID Connect)

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

https://developer.okta.com/docs/concepts/auth-servers/

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

Configuration

Defining an OpenID Connect Issuer

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

Application Type: “Web Application”
Redirect URL: Use your Posit Connect server address with the path /__login__/callback (i.e. https://HOST:PORT/__login__/callback).
Origin URL: Use your Posit Server or Posit 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 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 via the Posit 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 Posit Connect Server API.

Note

Searching against the remote authentication provider is not supported.

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

Unique ID

A user is uniquely identified in Posit 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 Posit 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 Posit 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, Posit 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

Posit Connect will rely on the value of the claim configured in OAuth2.UsernameClaim to obtain a username. By default, Posit 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 IDE does not support duplicate usernames when publishing to the same Posit 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 Posit 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 Posit Connect enforce the presence of the claim. That ensures Posit 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 Posit Connect itself.

The setting OAuth2.RequireUsernameClaim can be used for this purpose and Posit 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 Posit 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 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 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 Posit 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 Posit 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 Posit 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 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

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 Posit Connect Server API can be used to manage these groups as well.

Posit Connect obtains users group membership information from the claim configured in the option OAuth2.GroupsClaim.

By default, Posit 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 Posit 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 Posit Connect instead.

Manual Group Provisioning

Admins may use the “People” tab within the Posit Connect dashboard to “add” references to OpenID managed groups. Group membership of Posit 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 Posit 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, Posit Connect can also automate the management of groups themselves. By using OAuth2.GroupsAutoProvision Posit 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 Posit 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 Posit 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 Posit Connect Server API are always associated with a user.

Posit 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 Posit 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 Posit 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 Posit 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 Posit Connect, set Authorization.UserGroups to false in addition to an empty OAuth2.GroupsClaim.

Matching Groups’ Identifiers

By default, Posit Connect will match the list of groups send by the OpenID Connect authentication provider against the names of the groups that exist in Posit 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 Posit 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 Posit 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, Posit Connect can be configured to match these identifiers by using the setting OAuth2.GroupsByUniqueId.

Warning

This is considered to be an advanced feature in Posit Connect. Identifying groups by an identifier other than their name requires the use of the Posit Connect Server API for all group management workflows. The Posit 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 Posit Connect using the Posit 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. Posit 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 Posit 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 Posit 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 Posit 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. Posit Connect offers some options that allow adjusting these values to match your OpenID Connect authentication service provider.

Customizing Scopes

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