User Provisioning

Workbench

Overview

Posit Workbench can be configured to automatically manage local accounts for users that authenticate via an external identity provider (IdP).

Workbench supports two methods of native user and group provisioning:

  • An identity provider (IdP) provisions users and groups externally using the System for Cross-domain Identity Management (SCIM) protocol. For more details on the SCIM specification, see the SCIM: System for Cross-domain Identity Management documentation.
  • Users are provisioned via Just-in-Time (JIT) provisioning. Reference the Just-in-Time Provisioning section of this guide for more information on configuring JIT.

Supported IdPs

Workbench currently supports the following IdPs for user provisioning (support for other IdPs may be added in the future):

Prerequisites

  • Single Sign-On (SSO) must be configured in Workbench. Reference the OpenID Connect Authentication or the SAML Single Sign-On (SSO) Authentication sections of this guide for more information.
  • A mechanism for provisioning user home directories must be configured in the system. See the Home directories section of this guide for more information.
  • Workbench, or an external proxy in front of Workbench, must be configured to use HTTPS with a Certificate Authority (CA) signed certificate. See the Running with a Proxy section of this guide for more information on how to configure Workbench to use a proxy, and the Set Up SSL section of this guide for more information on how to configure Workbench to use HTTPS.

How it works

Provisioning

When a user is assigned to the Workbench application in the IdP, the IdP sends a request to Workbench to create a new user. Workbench assigns a unique user ID (UID), home directory, and POSIX username to the user.

Workbench stores the following information for each user derived from the IdP:

  • user_id: The user ID (UID) of the user, used as the POSIX/Operating-System-Level ID of the user.
  • user_name: The user’s username as provided by the IdP.
  • posix_name: The user’s POSIX username is used to authenticate the user via PAM and to create the user’s home directory. By default, this is the same as the user’s user_name with any domain suffix removed.
  • homedir: The user’s home directory.
  • is_admin: A boolean value indicating whether or not the user is an Administrator.
  • shadow: The user’s shadow password. This is the password that is used to authenticate the user via PAM.
  • display_name: The user’s display name as provided by the IdP.
  • email: The user’s email address as provided by the IdP.

This information is stored in the licensed_users table in the Workbench database. See the Data Dictionary for more information.

User ID assignment

When a user is created, Workbench assigns a UID to the user. The UID is used as the POSIX/Operating-System-Level ID of the user. By default, Workbench begins provisioning users with a minimum UID of 1000, but this is configurable. See the Configuring the minimum starting UID for provisioned users section for more information.

Workbench checks for UID and GID collisions when creating a new user. When an available UID is found, Workbench verifies that it is also available as a GID.

It is possible for the IdP to provide a UID in the provisioning request to Workbench, and Workbench uses the provided UID if it is available. If the provided UID is already in use by another user on the system, Workbench returns an error. See the section on Adding Workbench attributes to identity providers for more information.

Existing users on the system who were provisioned by another mechanism can be transferred to Workbench user provisioning. When existing users are transferred to Workbench user provisioning, they maintain their existing UID. Workbench derives the POSIX username from the username provided by the IdP and performs a lookup to find the existing UID for the user. See the Transferring Existing Users section for more information.

SCIM API

When user provisioning is enabled, Workbench hosts an endpoint that implements the SCIM protocol. The IdP uses this endpoint to create, update, and delete users in Workbench. Workbench uses this endpoint to retrieve user information.

The endpoint is hosted at the following URL:

https://<workbench-hostname>/scim/v2

Workbench uses a bearer token to authenticate requests to the SCIM API. See the Managing tokens section below for more information on managing Workbench user service tokens.

Group Provisioning

Workbench stores the following information for each group:

  • group_id: The group ID (GID) of the group, used as the POSIX/Operating-System-Level ID of the group.
  • name: The group’s POSIX name used at the Operating System level.
  • display_name: The group’s display name as provided by the IdP.
  • uuid: A unique identifier for the group.

Workbench stores this information in the groups table and stores group membership in the groups_licensed_users table, which associates users with their respective groups.

Group ID and name assignment

When Workbench creates a group, it assigns a GID to the group. Workbench uses the GID as the POSIX/Operating-System-Level ID for the group. By default, Workbench provisions groups starting with a minimum GID of 1000, but you can configure this. See the Configuring the minimum starting GID for provisioned groups section for more information.

The IdP can provide a GID in the provisioning request to Workbench, and Workbench uses the provided GID if it is available. If the provided GID is already in use by another group on the system, Workbench returns an error. See the section on Adding Workbench attributes to identity providers for more information.

If names are not already valid UNIX group names, names provided will be coerced into valid UNIX group names. Specifically, this means the following transformation may occur:

  • The name is converted to all lowercase letters.
  • All spaces are replaced with underscores (_).
  • Any character that is not a letter, digit, underscore, or hyphen is replaced with an underscore and consecutive underscores are collapsed into a single underscore.
  • If the name is empty, starts with a digit, or does not start with a letter or underscore, group_ is prepended.
  • The name is truncated to a maximum of 32 characters.

If any changes were made, Workbench logs the original name, the final name, and the transformations applied.

NSS module

Workbench provides a Name Service Switch (NSS) module that queries the Workbench SCIM API to surface users and groups from a Workbench instance to a local Linux system. The system uses this module to retrieve necessary user and group information. When you install Workbench, the NSS module is installed on the system and supports the following NSS databases:

  • passwd
  • group
  • shadow

Workbench requires this NSS module for user and group provisioning. Workbench, sessions, and other components use the NSS module to retrieve user and group information.

Reference Name Service Switch - Wikipedia for additional information on NSS.

Back to top