Lab 4 – Enable Admin Dashboard, Health Check, and API Endpoints

1 Learning Objectives

By the end of this lab, you will be able to:

  • Enable and configure the Administrative Dashboard with appropriate group-based access controls
  • Enable the Health Check endpoint for monitoring and load balancing purposes
  • Configure and use the Workbench API at different permission levels (user, admin, super-admin)
  • Generate API tokens with appropriate scopes and expiration settings
  • Describe the security implications of each endpoint and implement access controls

2 Introduction

Workbench provides several powerful management and monitoring endpoints that are disabled by default for security reasons. In this lab, you will enable and configure three critical endpoints: the Administrative Dashboard for monitoring and managing user sessions, the Health Check endpoint for load balancer integration, and the Workbench API for programmatic access and automation.

Each endpoint presents different security considerations:

  • The Admin Dashboard, if not configured with proper access controls, allows users to execute administrative actions on other sessions, including logging into Workbench as another user and starting sessions with their permissions.
  • The Health Check endpoint is not authenticated and some security-focused organizations consider it a security risk, but it is useful for monitoring the status of Workbench and determining whether an instance should be considered “up” in a load balancing context.
  • The Workbench API provides programmatic access to Workbench functionality for automation and integration with other systems. The API provides different permission levels (user, admin, super-admin) that control what actions API tokens can perform.

In this lab, you will:

  1. Enable and configure the admin dashboard with group-based access controls
  2. Enable and customize the health check endpoint
  3. Enable and test the Workbench API at the super-admin level
NoteTimings for this chapter
  • Reading time: 15 minutes
  • Documentation reading time: 25-35 minutes
  • Hands-on exercise time: 15-30 minutes
TipRequired Reading

3 Enabling the Admin Dashboard

Let’s enable the admin dashboard so you can explore what it can do.

Following the instructions in the documentation, edit the /etc/rstudio/rserver.conf file to enable the admin dashboard and give access to it to both the data-science-leadership and the senior-analysts. The former will also be admin superusers.

To enable the admin dashboard, add the following lines to /etc/rstudio/rserver.conf:

/etc/rstudio/rserver.conf
admin-enabled=1
admin-group=senior-analysts
admin-superuser-group=data-science-leadership

Restart Workbench, log in as one of the members of either the data-science-leadership or senior-analysts group (e.g., elena.rodriguez) and append /admin to your instance’s URL to access the dashboard.

In a different tab, open Workbench and create a new session. You can also open a private tab or a different browser and log in as another user. In the admin dashboard, explore the different sections to see what information you can access and what actions you can perform.

Among some of the tasks that you can perform in the admin dashboard, you can:

  • View real-time CPU and memory utilization for all active sessions
  • See which users are logged in and what they are running
  • Monitor system-wide resource usage (CPU, memory, active sessions, system load)
  • Forcibly terminate sessions
  • Review per-user historical data: session time, memory usage, CPU usage, logs
  • Examine system statistics over time
  • Inspect server logs
  • Lock/unlock users to prevent sign-ins
  • Monitor license usage and user limits

4 Enabling the Health Check Endpoint

The Health Check endpoint provides a simple way for load balancers and monitoring systems to verify that Workbench is running and responding. Because it is unauthenticated, you must explicitly enable it.

Using the Health Check documentation as a reference:

  1. Enable the Health Check endpoint in your Workbench configuration
  2. Restart Workbench to apply the changes
  3. Open a Private or Incognito browser window (to test without authentication) and verify that you can reach the health check endpoint by appending /health-check to your instance’s URL

The endpoint should return a simple status message indicating that Workbench is running.

Customizing the endpoint: For security through obscurity, you can change the health check endpoint path. Using the information in the documentation, modify your configuration to change the endpoint path to /health-check-secret and verify that it works at the new location.

To enable the health check endpoint, and to customize the endpoint path, add this to /etc/rstudio/rserver.conf:

/etc/rstudio/rserver.conf
server-health-check-enabled=1
server-health-check-custom-path=/health-check-secret

Remember to restart Workbench after making changes to rserver.conf.

5 Enabling and Using the Workbench API

The Workbench API is useful for remotely checking information about Workbench, as well as remotely launching Workbench jobs and sessions.

TipWhy is it relevant to me?

Understanding these administrative endpoints enables you to support your data science teams more effectively. The Admin Dashboard provides visibility into resource usage patterns. The Health Check endpoint integrates Workbench with your existing monitoring and load balancing infrastructure. The API enables automation of common tasks.

There are three different levels of access to the same set of API endpoints:

  • At the user level, the API can only be used by that user to interact with their own sessions
  • At the admin level, the API can be used to interact with any system user
  • At the super-admin level, the API can also be used to impersonate users and launch sessions on their behalf

Two settings control these levels:

  • At the token level: the token is generated with a permission level attached to it
  • At the system level: configure Workbench to limit the permission level available to the API

It is always possible to generate an API token at any permission level, but they will only work if the server is configured to accept them.

On the server side, each permission level is controlled by a different setting in /etc/rstudio/rserver.conf, giving you granular control over which levels of the API you want to enable for your instance. To enable all three levels, add the following lines to your rserver.conf file:

/etc/rstudio/rserver.conf
# Enable user level tokens
workbench-api-enabled=1

# Enable admin level tokens
workbench-api-admin-enabled=1

# Enable super-admin level tokens
workbench-api-super-admin-enabled=1

Restart Workbench after editing the rserver.conf file.

To generate tokens, you need to use the rstudio-server generate-api-token command as described in the documentation. Tokens can be generated with the --read-only option to limit their scope to non-destructive actions (in this case, admin and super-admin tokens will have the same privileges). Tokens can also be generated to be valid for a set number of days.

Important

Tokens are only displayed once when generated. They are stored encrypted and cannot be recovered. Record their values immediately.

As a convenience, the generate-api-token command can accept a predetermined 32-character string via the --token option. Alternatively, use --token-env to pass the name of an environment variable containing that string.

5.1 Testing the API

To test the API in your instance:

  1. Enable the super-admin level API for your installation by adding workbench-api-super-admin-enabled=1 to /etc/rstudio/rserver.conf
  2. Restart Workbench to apply the configuration change
  3. Generate a super-admin level token using the rstudio-server generate-api-token command
  4. Use the following API call to list the users known to Workbench (replace <token> with your actual token):
Terminal
export API_TOKEN=<token>
curl --location https://$HOSTNAME.$_SANDBOX_ID.instruqt.io/api/get_users \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $API_TOKEN" | jq
  1. Observe the output, which shows information about active users and their sessions. Open another browser or use incognito/private mode to log in as another user, then run the API call again to see how the output changes with additional active sessions.

6 Check your understanding

  1. What are the three permission levels available for Workbench API tokens, and what distinguishes the highest level from the others?

  2. What is the difference between the admin-group and admin-superuser-group settings in the Administrative Dashboard configuration?

  3. What happens to API tokens after they are generated, and what implications does this have for token management?

  1. The three levels are: user (can only interact with own sessions), admin (can interact with any user’s sessions), and super-admin (can also impersonate users and launch sessions on their behalf). The super-admin level is the only one that allows user impersonation.

  2. The admin-group grants users access to view and manage sessions and system resources, while the admin-superuser-group provides additional privileges such as the ability to impersonate other users and perform more sensitive administrative actions.

  3. API tokens are only displayed once when generated and are then stored in encrypted form. They cannot be recovered later. This means administrators must record token values immediately upon generation or use the --token or --token-env options to provide predetermined token values.