Skip to main content

Settings

The Settings interface provides a centralized control panel for configuring Workshop's global settings that affect all hosts in your organization. This dashboard allows administrators to manage default sync settings, removable media blocking behavior, and user access.

Default Client Mode​

The Client Mode setting determines the default enforcement behavior for all Santa agents across your organization:

  • Monitor: Allows all executions but logs them for review
  • Lockdown: Only allows executions that match allowlist rules
  • Standalone: Operates without connecting to the sync server

Individual hosts can be assigned different modes that override this global default.

Learn more about modes

On-Demand Monitor Mode​

On-Demand Monitor Mode allows hosts to temporarily transition into Monitor Mode for a limited duration. This feature is useful when users need to execute applications that would normally be blocked in Lockdown mode, without permanently changing the host's enforcement mode.

When enabled, hosts can request temporary Monitor Mode access through the Santa client. The duration of this temporary access is controlled by two settings:

  • Max Minutes: The maximum number of minutes a machine is allowed to transition into Monitor Mode. Valid range: 1-43,200 minutes (1 minute to 30 days). This setting acts as an upper bound for any Monitor Mode request.

  • Default Duration Minutes: The default number of minutes of Monitor Mode granted when requested if no duration is explicitly specified. If set to 0 or not specified, the Max Minutes value is used as the default. This value must not exceed Max Minutes.

When On-Demand Monitor Mode is disabled, hosts cannot request temporary Monitor Mode access and must rely on their configured Client Mode setting.

Removable Media Blocking​

Removable media blocking controls whether Santa will block the mounting of removable storage devices:

  • Disabled: removable media devices can be mounted normally
  • Enabled: removable media devices will be blocked from mounting
  • Enabled with Remount Flags: removable media devices will be blocked, but can be remounted with specific flags

Sync Intervals​

Sync Intervals control how frequently Santa agents communicate with the Workshop server to retrieve updated rules and configurations.

  • Full Sync Interval: Determines how often hosts perform a progressive sync with the server. Valid range: 60-86,400 seconds (1 minute to 24 hours). Default is 600 (10 min).

  • Push Notification Full Sync Interval: When Push Notifications are enabled, this setting determines how often hosts perform a progressive sync with the server. Valid range: 60-86,400 seconds (1 minute to 24 hours). Default is 14400 (4 hours).

Santa Auth​

Workshop supports two methods for authenticating Santa clients. Changes to authentication methods will affect the generated config shown on the Santa tab. If both Token and mTLS authentication are enabled, the config will use the mTLS configuration.

Token Authentication​

Token-based authentication allows Santa clients to authenticate using bearer tokens. You can manage authentication tokens from the Settings interface:

  • Multiple Tokens: Create and manage multiple authentication tokens for different deployments or environments
  • Last Used Tracking: Each token displays the timestamp of its last use, helping you identify active and inactive tokens
  • Token Deletion: Tokens can be deleted when they are no longer needed, immediately revoking access for any clients using that token

When using token authentication, Santa clients connect to the standard SyncBaseURL (e.g., https://tenant.workshop.cloud/santa).

mTLS Authentication​

Mutual TLS (mTLS) authentication provides certificate-based authentication for enhanced security. Workshop supports configuring multiple Certificate Authority (CA) certificates from the Settings interface, allowing you to manage certificates for different organizational units or for seamless transition between issuing CAs.

When mTLS is enabled, the SyncBaseURL key in Santa's configuration will include an mtls. prefix (e.g., https://mtls.tenant.workshop.cloud/santa). This special URL only works when mTLS authentication is properly configured on both the Workshop server and the Santa client.

Important: The mTLS-prefixed URL will only accept connections from clients presenting valid certificates signed by one of the configured CA certificates. Standard token-based authentication will not work with the mTLS URL.

User Management​

Workshop has two distinct user systems that serve different purposes:

  1. SSO Users: Users who can log into the Workshop web interface
  2. Directory Users & Groups: Users and groups that represent your organization's identity structure for policy assignment

SSO Users​

SSO Users are those who can access the Workshop web interface. These users authenticate via Single Sign-On (SSO) through your identity provider.

From the Settings page, you can:

  • Configure SSO: Set up your identity provider connection
  • Verify Domains: Confirm ownership of your organization's email domains
  • Manage Users: View and manage users who can log into Workshop
  • Assign Roles: Control permissions by assigning roles to SSO users

Directory Users & Groups​

Directory Users and Groups represent your organization's identity structure. When a host reports its primary user, Workshop looks up that user in the directory to determine which groups they belong to. Groups can have tags assigned to them, which are then automatically applied to the host.

This enables powerful policy automation: instead of manually tagging each host, you can assign tags to groups in your directory, and hosts will automatically inherit the correct tags based on their primary user.

Directory Type​

Workshop supports two modes for managing Directory Users and Groups:

Directory Sync (DSYNC)​

In DSYNC mode, users and groups are automatically synchronized from an external directory service via SCIM.

Advantages:

  • Users and groups stay in sync with your identity provider(IdP)'s external directory automatically
  • No manual maintenance required
  • Changes in your identity provider(IdP)'s external directory are reflected in Workshop
  • Leverage existing group structures for policy assignment

Configuration:

  1. Set the Directory Type to "Directory Sync"
  2. Click "Configure Directory Sync" to set up the SCIM connection
  3. Use "Trigger Directory Sync" to force an immediate sync

Local Directory​

In Local mode, users and groups are created and managed manually within Workshop.

Advantages:

  • No external directory service required
  • Full control over user and group definitions
  • Useful for testing or organizations without centralized identity management
  • Can define groups that don't exist in your identity provider(IdP)'s external directory

Configuration:

  1. Set the Directory Type to "Local"
  2. Create users and groups directly in the Users and Groups tabs or via the API
  3. Manually assign users to groups as needed or via the API
warning

Changing the directory type will delete all existing users and groups of the current type. This action cannot be undone.

Assigning Groups to Hosts​

There are two ways hosts can be associated with groups:

Via Primary User​

When using Directory Sync, Workshop automatically looks up the host's primary user in the directory and applies tags from any groups that user belongs to. This happens during each Santa sync.

For example, if user alice@example.com is the primary user of a MacBook and she's a member of the "Engineering" group in your IdP's external directory, the MacBook will automatically receive any tags assigned to the "Engineering" group in Workshop.

Via Primary User Groups (Client-Defined)​

Starting with Santa version 2025.6, you can define primary user groups directly in the Santa configuration. Workshop will look up these group names in the directory and apply their tags, even if the primary user isn't a member of those groups in your IdP's external directory.

See Tags for more details on how group membership affects tag assignment.

Slack​

See Slack Settings for more information.

Workshop Updates​

Workshop provides flexible update management to keep your server current with the latest features, improvements, and security patches. You can choose between automatic updates with configurable policies or manual updates triggered on-demand.

Update Process​

Workshop's update mechanism is designed to be seamless and zero-downtime. When an update is triggered (either automatically or manually), the current version continues serving traffic during the update. Once the update completes, the new version automatically takes over. This ensures continuous availability throughout the update process.

All update activities are recorded in the audit log for compliance and troubleshooting purposes, whether triggered automatically by the system or manually by a user.

note

While the update process is seamless there can be a short period during the update where the web UI may attempt to partially load both old and new versions, causing errors. If this happens, wait a few minutes and refresh the page. This has no impact on Santa client syncing or API use.

Manual Updates​

You can manually trigger updates at any time, regardless of automatic update settings:

  1. Navigate to Settings → Administration in the Workshop interface
  2. In the Updates section, view the current version and available updates
  3. If updates are available, select the desired version from the dropdown
  4. Click Trigger Update to install the selected version immediately

Manual updates are not restricted by automatic update modes or time windows, giving you full control to update on your schedule. The triggering user is recorded as the actor in audit logs for manual updates.

Automatic Updates​

Workshop can automatically install updates based on policies you define, eliminating the need for manual intervention while maintaining control over when and what gets updated.

Automatic Update Modes​

Workshop provides three automatic update modes to match your organization's policies:

  • Disabled: Automatic updates are turned off. All updates must be triggered manually through the Workshop interface or API.

  • All Updates: Automatically installs all available Workshop updates as soon as they're released. Use this mode to stay current with the latest features and improvements.

  • Security Updates Only (Default): Automatically installs only updates that contain security fixes. Feature releases and other non-security updates are skipped. This mode is recommended for production environments that prioritize stability while ensuring critical security patches are applied promptly.

Update Scheduling​

When automatic updates are enabled, Workshop checks for updates every hour and installs them immediately if an update matching your configured mode is available. You can optionally restrict when automatic updates are installed by configuring a time window.

Update Window Configuration:

  • Any Time (Default): Updates can install during any hour. No restrictions are applied.

  • Specific Hours: Define a start hour and end hour (in your local timezone) to restrict automatic updates to a particular window. For example, configure updates to only install between 2:00 AM and 6:00 AM to minimize disruption during business hours.

  • Overnight Window: If the start hour is later than the end hour (e.g., 10:00 PM to 6:00 AM), the window wraps around midnight. This is useful for scheduling updates during off-hours.

note

Time windows are stored in UTC internally but displayed in your browser's local timezone for convenience. The system checks for available updates every hour, and if an update matching your mode is available and the current hour falls within your configured window, the update will be installed automatically.

Configuring Automatic Updates​

To configure automatic update settings:

  1. Navigate to Settings → Administration in the Workshop interface
  2. Scroll to the Automatic Updates section
  3. Select your preferred automatic update mode
  4. Optionally configure a time window to restrict when automatic updates can install
  5. Click Save Settings to apply your changes

Changes to automatic update settings are recorded in the audit log.

MCP​

See MCP for more information.