Configure Entra ID with OpenID Connect

Overview

This guide walks you through configuring Microsoft Entra ID 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 Entra ID 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 Entra ID 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 Entra ID 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 Entra ID 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 Entra ID.
  • You are comfortable with manual user deprovisioning.
  • You do not need Workbench GIDs to be synced from Entra ID groups.

Use SCIM if

  • You need Entra ID to centrally manage the full user lifecycle, including creation, updates, and automatic deactivation.
  • You need Workbench GIDs to be synced from Entra ID groups.
  • Your environment already meets the additional requirements: a CA-signed TLS certificate, and inbound HTTPS from Entra ID 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 Entra ID application

Note

Entra ID distinguishes between application registrations and enterprise applications.

  • Application registration: registers external access for an application
  • Enterprise application: tenant-specific; controls authentication and, optionally, user provisioning

This guide starts by creating the enterprise application through the non-gallery path because it sets the internal properties required to enable SCIM provisioning. This is still considered best practice, even if you are using JIT provisioning.

Create the enterprise application:

  1. In the Entra ID portal, go to Enterprise applications > New application.
  2. Select Create your own application.
  3. Enter a name (for example, Posit-Workbench-Production).
  4. Select Integrate any other application you don’t find in the gallery, then select Create.
  5. Under Manage > Properties, set Assignment required? to Yes, then assign users or groups under Manage > Users and groups.

Configure the linked app registration:

  1. From the enterprise application Properties page, select the Application registration link to open the linked app registration.
  2. Set the Redirect URI type to Web and enter https://<workbench-hostname>/openid/callback.
  3. Select Register.
  4. From the Overview page, copy the Application (client) ID and your Directory (tenant) ID. You will use both values later.
  5. Go to Manage > Certificates & secrets and create a new Client secret.
  6. Copy the client secret’s Value immediately. Make sure to copy the Value and not the Client ID. It cannot be retrieved later. You will use this value in Step 2.

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 Application (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. Open /etc/rstudio/rserver.conf and add the following lines. Replace <tenant-id> with the Directory (tenant) ID from Step 1:

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

# Configure Entra ID as the OpenID provider
auth-openid-issuer=https://login.microsoftonline.com/<tenant-id>/v2.0

# Configure the username claim (usually email or UPN)
auth-openid-username-claim=preferred_username

  4. Restart the Workbench services:

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

  5. Verify that Workbench restarted successfully:

    Terminal
    sudo systemctl status rstudio-server

Users assigned to the Workbench application in Entra ID 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 Entra ID.

Generate a token and copy the value:

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

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

Step 2: Configure Entra ID SCIM provisioning

  1. Open the enterprise Entra ID application created previously.

  2. Under Manage, select Provisioning, then set Provisioning Mode to Automatic.

  3. In Admin Credentials:

    • Tenant URL: https://<workbench-hostname>/scim/v2
    • Secret Token: Paste the token from Step 1.

  4. Under Provisioning, select Mappings, then select Provision Microsoft Entra ID Users. Review the list and confirm the mappings and attributes are correct.

  5. Test the connection and save.

Step 3: (Optional) Configure Entra ID SCIM group provisioning

Entra ID can synchronize groups assigned to the Workbench application. This is optional but recommended if you use groups for access control. You must assign groups to the Workbench application before Entra ID can provision them.

  1. Open the enterprise Entra ID application created previously.
  2. Under Manage, select Provisioning, then set Provisioning Status to On and save.
  3. Under Manage, select Users and groups, then select the users and groups that should be added.
Note

Entra ID limits group membership to 150. If a user is a member of more than 150 groups, Entra ID concatenates their group list, potentially missing important ones needed inside Workbench.

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 Entra ID, assign a test user to the Workbench application.

  2. Have the test user navigate to the Workbench URL and sign in using their Entra ID 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 Entra ID, 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 Entra ID 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 Entra ID.

Example: complete minimal configuration

Here is an example of a minimal configuration required for OIDC authentication with JIT provisioning:

/etc/rstudio/rserver.conf
www-port=8787
server-health-check-enabled=1
# auth-minimum-user-id=100
launcher-sessions-enabled=1
# Use localhost as your launcher address
launcher-address=localhost
launcher-port=5559
# Use the https address of your load balancer, proxy, or server
launcher-sessions-callback-address=https://workbench.example.com
launcher-default-cluster=Local

# OpenID
auth-openid=1
auth-openid-issuer=https://login.microsoftonline.com/example-example-example-example-example/v2.0

# JIT
user-provisioning-enabled=1
user-provisioning-register-on-first-login=1
auth-pam-sessions-enabled=1
/etc/rstudio/openid-client-secret
client-id="example-example-example-example-example"
client-secret="example"
Back to top