Configure Okta with OpenID Connect

Overview

This guide walks you through configuring Okta as an authentication provider for Posit Workbench using OpenID Connect (OIDC), and setting up automatic user provisioning. Where possible, Posit recommends using OIDC with Workbench to enable the most features (for example, integration with Azure and AWS Managed Credentials).

What you will accomplish

By the end of this guide, your Workbench server will:

  • Authenticate users against Okta using OIDC.
  • Automatically provision user accounts and home directories using SCIM or JIT provisioning.

Prerequisites

Before you begin, ensure you have:

  • Workbench installed and accessible.
  • Administrative access to Okta with permission to create and modify applications.
  • Administrative command line access to the Workbench server.
  • Sudo privileges on the Workbench server.
  • A valid SSL certificate with verified HTTPS access for Workbench. If you use an external proxy or load balancer, configure the front-door address with an SSL certificate.

If you plan to use SCIM for user provisioning, you also need:

  • A publicly trusted Certificate Authority (CA) signed certificate. Self-signed certificates are not supported for SCIM.
  • Network connectivity between your Posit servers and the Okta service, with port 443 (HTTPS) open.

If you are configuring SCIM and use the Slurm launcher, additional networking considerations apply. See Integrating with Slurm for details.

Choose a user provisioning strategy

Workbench supports two automatic user provisioning methods: Just-in-Time (JIT) and System for Cross-domain Identity Management (SCIM).

Comparison

JIT SCIM
Setup complexity Lower Higher
User provisioning Automatic Automatic
User deprovisioning Manual Automatic
Group sync with names Supported Supported
Group sync with Linux group IDs (GIDs) Not supported Supported
Requires CA-signed TLS certificate for Workbench No Yes
Requires inbound HTTPS from Okta to Workbench No Yes

Use JIT if

  • You want a simpler setup with fewer prerequisites.
  • You cannot configure HTTPS with a publicly trusted, CA-signed certificate for Workbench.
  • Your Workbench deployment cannot receive inbound connections from Okta.
  • You are comfortable with manual user deprovisioning.
  • You do not need Workbench GIDs to be synced from Okta groups.

Use SCIM if

  • You need Okta to centrally manage the full user lifecycle, including creation, updates, and automatic deactivation.
  • You need Workbench GIDs to be synced from Okta groups.
  • Your environment already meets the additional requirements: a CA-signed TLS certificate, and inbound HTTPS from Okta to the Workbench SCIM API endpoint at https://<workbench-hostname>/scim/v2.
TipSwitching provisioning methods

The rest of this guide shows JIT instructions by default. If you choose SCIM, select SCIM from the Provisioning selector below. Your selection is saved in your browser and persists across visits.

Configure authentication

Both provisioning strategies require OIDC authentication. Complete these steps before you configure user provisioning.

Step 1: Create the Okta application

  1. In Okta, go to Applications > Browse App Catalog.
  2. Search for Posit Workbench.
  3. Select Add Integration to add Workbench to your organization.
  4. Assign the users or groups that should have access to Workbench.
  5. From the Posit Workbench App > General tab, in the App Settings section, select Edit.
  6. In the Workbench Base URL box, enter the base URL of your Workbench server without the https:// prefix (for example, workbench.example.com), then select Save.
  7. Go to the Posit Workbench App > Sign On tab.
  8. Under Sign on methods:
    1. Select OpenID Connect.
    2. Set Application username format to Email prefix.
    3. Select Done.
  9. From the Sign On tab, copy the Client ID and Client secret. You will use these values when you configure Workbench.
  10. Copy the URL for OpenID Provider Metadata. You will use this URL when you configure Workbench.

Step 2: Encrypt the client secret

On the Workbench server, encrypt the client secret you copied in Step 1. For more details, see Encryption.

Terminal
sudo rstudio-server encrypt-password

Paste the plaintext client secret when prompted. Save the encrypted value. You will use it in Step 3.

Step 3: Configure Workbench for OIDC authentication

  1. On the Workbench server, create /etc/rstudio/openid-client-secret with the following content. Replace the placeholders with the Client ID from Step 1 and the encrypted client secret from Step 2:

    /etc/rstudio/openid-client-secret
    client-id=<your-client-id>
client-secret=<your-encrypted-client-secret>

  2. Set permissions on the file:

    Terminal
    sudo chmod 0600 /etc/rstudio/openid-client-secret
sudo chown rstudio-server:rstudio-server /etc/rstudio/openid-client-secret

  3. In a web browser, open the OpenID Provider Metadata URL you copied in Step 1. The URL returns a JSON document containing the Okta OpenID configuration.

  4. In the JSON document, locate and copy the issuer value (for example, https://<your-okta-tenant>.okta.com). You will use it in the next step.

  5. Open /etc/rstudio/rserver.conf and add the following lines. Replace <issuer-url> with the issuer value from Step 4:

    /etc/rstudio/rserver.conf
    # Enable OpenID Connect authentication
auth-openid=1

# Configure Okta as the OpenID provider
auth-openid-issuer=https://<your-okta-tenant>.okta.com

# Configure the username claim
auth-openid-username-claim=preferred_username

  6. Restart the Workbench services:

    Terminal
    sudo systemctl restart rstudio-server
sudo systemctl restart rstudio-launcher

  7. Verify that Workbench restarted successfully:

    Terminal
    sudo systemctl status rstudio-server

Users assigned to the Workbench application in Okta can now authenticate, but they cannot start sessions until you configure user provisioning.

Set up user provisioning

Workbench requires users to have local or networked system accounts. These need to be Linux users complete with home directories.

The following instructions are for JIT provisioning. To view SCIM instructions instead, select SCIM from the Provisioning selector in the Choose a user provisioning strategy section.

The following instructions are for SCIM provisioning. To view JIT instructions instead, select JIT from the Provisioning selector in the Choose a user provisioning strategy section.

Step 1: Configure Workbench for user provisioning

JIT

  1. Open the Workbench configuration file /etc/rstudio/rserver.conf to edit it for JIT.

  2. Add the following lines:

    /etc/rstudio/rserver.conf
    # Enable user provisioning
user-provisioning-enabled=1

# Enable user provisioning with JIT registration instead of SCIM
user-provisioning-register-on-first-login=1

# Enable Pluggable Authentication Modules (PAM) sessions for home directory creation
auth-pam-sessions-enabled=1

# Optional: Configure starting UID (default is 1000)
#user-provisioning-start-uid=1000

# Optional: Set custom home directory path (default is /home)
#user-homedir-path=/mnt/home

SCIM

  1. Open the Workbench configuration file /etc/rstudio/rserver.conf to edit it for SCIM.

  2. Add the following lines:

    /etc/rstudio/rserver.conf
    # Enable user provisioning
user-provisioning-enabled=1

# Enable Pluggable Authentication Modules (PAM) sessions for home directory creation
auth-pam-sessions-enabled=1

# Optional: Configure starting UID (default is 1000)
#user-provisioning-start-uid=1000

# Optional: Set custom home directory path (default is /home)
#user-homedir-path=/mnt/home

Step 2: Configure home directory creation

Workbench relies on PAM to create user home directories. Configure your operating system accordingly.

Terminal
# Install the PAM mkhomedir module if not already installed
sudo apt update
sudo apt install -y libpam-modules

# Configure automatic home directory creation
echo -e "\n# Posit Workbench: automatic home directory creation\nsession required pam_mkhomedir.so skel=/etc/skel/ umask=0077" | sudo tee -a /etc/pam.d/common-session
Terminal
# Install required packages
sudo dnf install -y oddjob-mkhomedir authselect

# Enable the oddjobd service for home directory creation
sudo systemctl enable --now oddjobd.service

# Enable the home directory creation feature
sudo authselect enable-feature with-mkhomedir
sudo authselect apply-changes

Step 3: Configure NSS module

Workbench includes a Name Service Switch (NSS) module that allows the operating system to resolve usernames based on the Workbench user service.

  1. Verify the NSS module is installed:

    Terminal
    ls -l /usr/lib/x86_64-linux-gnu/libnss_pwb.so.2

  2. Modify the /etc/nsswitch.conf NSS configuration file lines passwd, group, and shadow to include pwb if the file does not already list it:

    /etc/nsswitch.conf
    passwd:         files systemd pwb
group:          files systemd pwb
shadow:         files pwb
Note

If you have System Security Services Daemon (SSSD) or Active Directory configured, ensure pwb appears before sssd in the configuration to prioritize Workbench users.

  1. Verify the NSS module is installed:

    Terminal
    ls -l /usr/lib64/libnss_pwb.so.2

  2. Create a custom authselect profile:

    Terminal
    sudo authselect create-profile pwb --base-on=minimal
Note

If you have SSSD configured, use --base-on=sssd instead of --base-on=minimal.

  1. Modify the passwd, group, and shadow lines to include pwb in the profile configuration /etc/authselect/custom/pwb/nsswitch.conf:

    /etc/authselect/custom/pwb/nsswitch.conf
    passwd:     files {if "with-altfiles":altfiles }systemd pwb {exclude if "with-custom-passwd"}
group:      files {if "with-altfiles":altfiles }systemd pwb {exclude if "with-custom-group"}
shadow:     files pwb                                       {exclude if "with-custom-shadow"}
Note

If you have SSSD or Active Directory configured, ensure pwb appears before sssd in the configuration to prioritize Workbench users.

  1. Activate the profile:

    Terminal
    sudo authselect select custom/pwb with-mkhomedir
sudo authselect apply-changes

Step 4: Disable NSCD caching

Name Service Cache Daemon (NSCD) caching can interfere with the Workbench user provisioning process. Disable it for user and group lookups. Workbench user provisioning implements its own caching mechanism.

First, check if you are using NSCD:

Terminal
sudo systemctl status nscd

If NSCD is installed and running, make the following changes.

  1. Add or modify these lines:

    /etc/nscd.conf
    enable-cache passwd no
enable-cache group no

  2. Restart NSCD:

    Terminal
    sudo systemctl restart nscd

Enable SCIM provisioning

Step 1: Generate the SCIM authentication token

Workbench uses a bearer token to authenticate SCIM requests from Okta.

Generate a token and copy the value:

Terminal
sudo rstudio-server user-service generate-token "Okta User Provisioning Token"
Warning

Store this token securely. Anyone with this token can create, modify, or delete users in Workbench.

Step 2: Configure Okta SCIM provisioning

The Okta Marketplace integration for Posit Workbench does not support user provisioning with SCIM. You must create a separate app integration for user provisioning. This second app integration must use SAML, because Okta custom OIDC applications do not support user provisioning. See this Okta support article for details.

  1. In Okta, go to Applications > Create App Integration.
  2. Select SAML 2.0.
  3. Enter a name such as Posit Workbench SCIM (choose any name, but make it clear that this integration is for SCIM).
  4. Fill out the following SAML Settings:
    1. Single sign-on URL: https://<workbench-hostname>/saml/acs (include https://)
    2. Audience URI (SP Entity ID): https://<workbench-hostname>/saml/metadata (include https://)
    3. Name ID format: Unspecified
    4. Application username: Email prefix
  5. Select the General tab.
  6. Select Edit in the App Settings section and check Provisioning: SCIM.
  7. Select the Provisioning tab.
  8. Select Integration.
  9. Select Edit in the SCIM Connection section.
  10. Configure the following settings:
    • SCIM connector base URL: https://<workbench-hostname>/scim/v2
    • Unique identifier field for users: userName
    • Supported provisioning actions: select Push New Users, Push Profile Updates, and Push groups.
    • Authentication Mode: select HTTP Header. In the Authorization box, paste the token from Step 1. Select Test Connector Configuration to verify the connection.
  11. If the test succeeds, select Save.
  12. Select the To App tab.
  13. Select Edit.
  14. Enable Create Users, Update User Attributes, and Deactivate Users.
  15. Select Save.

Step 3: (Optional) Configure Okta SCIM group provisioning

Okta can synchronize groups assigned to the Workbench application. This is optional but recommended if you use groups for access control.

  1. Select the Push Groups tab.
  2. Select + Push Groups.
  3. Find the group you want to push and select Save.
  4. If successful, the Push Status changes to Active.

Restart Workbench

Restart Workbench to apply the configuration changes.

Terminal
sudo systemctl stop rstudio-server
sudo systemctl stop rstudio-launcher
sudo systemctl start rstudio-launcher
sudo systemctl start rstudio-server

Verify that Workbench has restarted successfully:

Terminal
sudo systemctl status rstudio-server
sudo systemctl status rstudio-launcher

Verification

After completing configuration, test that authentication and provisioning work correctly and that Workbench starts successfully without error messages.

  1. In Okta, assign a test user to the Workbench application.

  2. Have the test user navigate to the Workbench URL and sign in using their Okta credentials.

  3. After the user’s first successful sign-in, verify that Workbench created the account:

    Terminal
    sudo rstudio-server list-users

    The test user should appear in the output.

  4. Verify that the user can start a session successfully.

  1. In Okta, assign a test user to the Workbench application.

  2. Verify that Workbench provisioned the user:

    Terminal
    sudo rstudio-server list-users

    The test user should appear in the output.

  3. Have the test user navigate to the Workbench URL and sign in using their Okta credentials.

  4. Verify that the user can start a session successfully.

Troubleshooting

Use the pamtester utility for additional testing:

Terminal
/usr/lib/rstudio-server/bin/pamtester --verbose rstudio <user> authenticate acct_mgmt setcred open_session close_session

If you encounter any issues, open a ticket with Posit Support. Include a copy of your diagnostic output, any error messages, and screenshots of your configured applications in Okta.

Back to top