Managing Users with SCIM

Workbench

When Posit Workbench is configured to use automatic user provisioning, users are managed through Workbench’s System for Cross-domain Identity Management (SCIM) API. We recommend managing users through your Identity Provider (IdP), however the SCIM API can be used to manage users directly.

Warning

We recommend using the SCIM API for user management only when necessary, such as updating Workbench-specific attributes that cannot be managed through your IdP without additional configuration. Managing users directly with the SCIM API can lead to inconsistencies between Workbench and your IdP and should be done with caution.

Authentication

The SCIM API requires an API token for authentication. See Managing Tokens for more information on creating and managing tokens for the SCIM API.

Schema

The full SCIM User schema for Workbench can be queried by making a GET request to the /scim/v2/Schemas endpoint.

curl -H "Authorization: Bearer $TOKEN" \
  https://<workbench-hostname>/scim/v2/Schemas

User management

Get users

To retrieve a list of all users provisioned to Workbench, make a GET request to the /scim/v2/Users endpoint.

curl -H "Authorization: Bearer $TOKEN" \
  https://<workbench-hostname>/scim/v2/Users
{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "startIndex": 1,
  "itemsPerPage": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User",
        "urn:rstudio:params:scim:schemas:extension:workbench:1.0:User"
      ],
      "id": "1",
      "meta": {
        "resourceType": "User",
        "created": "2024-04-23T18:57:43",
        "lastModified": "2024-04-23T19:23:55",
        "location": "/Users/1",
        "version": "9ab7267e29989dbc"
      },
      "userName": "user@example.com",
      "name": {
        "formatted": "User Name",
        "familyName": "Name",
        "givenName": "User"
      },
      "emails": [
        {
          "value": "user@example.com",
          "type": "work",
          "primary": true
        }
      ],
      "urn:rstudio:params:scim:schemas:extension:workbench:1.0:User": {
        "admin": false,
        "posixUserId": 1001,
        "posixUserName": "user",
        "homeDirectory": "/home/user",
        "locked": false,
        "lastSignIn": "2024-04-23T22:23:55",
      }
    }
  ]
}

Get User

To retrieve information about a specific user, make a GET request to the /scim/v2/Users/{id} endpoint, where {id} is the user’s ID.

Important

The user’s ID in this context is not the user’s POSIX ID, but the user’s SCIM ID that corresponds to the id attribute in the SCIM user object.

curl -H "Authorization: Bearer $TOKEN" \
  https://<workbench-hostname>/scim/v2/Users/{id}
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:rstudio:params:scim:schemas:extension:workbench:1.0:User"
  ],
  "id": "1",
  "meta": {
    "resourceType": "User",
    "created": "2024-04-23T18:57:43",
    "lastModified": "2024-04-23T19:23:55",
    "location": "/Users/1",
    "version": "9ab7267e29989dbc"
  },
  "userName": "user@example.com",
  "name": {
    "formatted": "User Name",
    "familyName": "Name",
    "givenName": "User"
  },
  "emails": [
    {
      "value": "user@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "urn:rstudio:params:scim:schemas:extension:workbench:1.0:User": {
    "admin": false,
    "posixUserId": 1001,
    "posixUserName": "user",
    "homeDirectory": "/home/user",
    "locked": false,
    "lastSignIn": "2024-04-23T22:23:55",
  }
}

Updating users

The following Workbench attributes can be updated with the SCIM API:

  • urn:rstudio:params:scim:schemas:extension:workbench:1.0:User:posixName
  • urn:rstudio:params:scim:schemas:extension:workbench:1.0:User:posixUid
  • urn:rstudio:params:scim:schemas:extension:workbench:1.0:User:homeDirectory
  • urn:rstudio:params:scim:schemas:extension:workbench:1.0:User:admin

Updating attributes with PATCH requests

To update user attributes with a PATCH request, specify the urn:ietf:params:scim:api:messages:2.0:PatchOp schema and the Operations array with the op, path, and value fields:

  • op: The operation to perform. Can be one of add, remove, or replace.
  • path: The path to the attribute to update.
  • value: The new value of the attribute.

For example, to update a user’s admin status to true, make the following request:

curl -X PATCH  https://<workbench-hostname>/scim/v2/Users/{id} \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "replace",
        "path": "urn:rstudio:params:scim:schemas:extension:workbench:1.0:User:admin",
        "value": true
      }
    ]
  }'
{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:rstudio:params:scim:schemas:extension:workbench:1.0:User"
  ],
  "id": "1",
  "meta": {
    "resourceType": "User",
    "created": "2024-04-23T18:57:43",
    "lastModified": "2024-04-23T19:23:55",
    "location": "/Users/1",
    "version": "9ab7267e29989dbc"
  },
  "userName": "user@example.com",
  "name": {
    "formatted": "User Name",
    "familyName": "Name",
    "givenName": "User"
  },
  "emails": [
    {
      "value": "user@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "urn:rstudio:params:scim:schemas:extension:workbench:1.0:User": {
    "admin": true,
    "posixUserId": 1001,
    "posixUserName": "user",
    "homeDirectory": "/home/user",
    "locked": false,
    "lastSignIn": "2024-04-23T22:23:55",
  }
}

Multiple operations can be included in the Operations array to update multiple attributes in a single request.

Back to top