Admin Dashboard, Health Check, and the Workbench API
By the end of this lesson, you will be able to:
- Describe the administrative endpoints Workbench provides and why they are disabled by default
- Explain how group-based access controls protect the admin dashboard
- Explain the role of the health check endpoint in monitoring and load balancing
- Distinguish the three permission levels of the Workbench API
1 Introduction
Workbench provides several management and monitoring 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. All three are disabled by default, because each one widens what can be done against your server and needs a deliberate access decision from you.
This lesson explains what each endpoint does and the security considerations that come with it. The accompanying lab has you enable them one by one, with access controls in place.
- Reading time: 15 minutes
- Documentation reading time: 25-35 minutes
- Hands-on exercise time: 15-30 minutes
2 The Administrative Dashboard
The admin dashboard gives administrators visibility into the server: real-time CPU and memory usage per session, who is logged in and what they are running, system statistics over time, server logs, and license usage. It also allows forceful actions, such as terminating sessions and locking users out.
Access is controlled by two settings in rserver.conf: admin-group grants a Linux group access to view and manage sessions and system resources, and admin-superuser-group grants a group additional privileges, such as impersonating other users. Because a misconfigured dashboard would let ordinary users execute administrative actions on other sessions, including starting sessions with another user’s permissions, these groups should be restricted to the people who genuinely need them.
3 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, for example to decide whether an instance should be considered “up”.
It is intentionally unauthenticated, so it must be enabled explicitly. Some security-focused organizations consider an unauthenticated endpoint a risk. If that applies to your organization, you can change the endpoint path to something of your choosing.
4 The Workbench API
The Workbench API provides programmatic access to Workbench functionality, such as inspecting users and sessions, and launching jobs and sessions remotely. It is useful for automation and integration with other systems.
Access is governed at two levels:
- Token level: each token is generated with a permission level attached to it, and can be restricted with the
--read-onlyoption or given an expiration in days. - Server level: three settings in
rserver.confcontrol which permission levels the server accepts, so you can enable exactly as much as you need.
The three levels are:
user: the token holder can interact with their own sessions.admin: the token holder can interact with any system user.super-admin: the token holder can also impersonate users and launch sessions on their behalf.
Tokens are generated with rstudio-server generate-api-token. They are displayed only once, are stored encrypted, and cannot be recovered, so record their values immediately.
Understanding these administrative endpoints lets you support your data science teams more effectively. The dashboard gives you visibility into resource usage patterns before they become problems. The health check endpoint integrates Workbench with the monitoring and load balancing infrastructure you already run. The API enables automation of common administrative tasks.
In the accompanying lab, you will enable the admin dashboard with group-based access controls, turn on and customize the health check endpoint, and test the Workbench API with a super-admin token.