Skip to main content

On-Premises Client Onboarding Guide

This guide walks you through setting up a Surface Security appliance on your network and connecting it to your Active Directory environment.

Prerequisites​

Before beginning onboarding, ensure you have:

  • Surface Security appliance -- powered on and connected to your network
  • Network access -- DHCP or a static IP assignment for the appliance
  • DNS record -- pointing to the appliance (e.g., surfacesec.yourcompany.com)
  • TLS certificate -- for your domain, or use Let's Encrypt auto-provisioning
  • License key -- provided by your Surface Security account team
  • Active Directory access (optional) -- for LDAP-based directory sync

Step 1: Appliance Setup​

Physical Setup​

  1. Unbox the appliance and connect:
    • Power: Connect the supplied power adapter
    • Network: Connect Ethernet to your corporate network
    • Display (optional): Connect a monitor for first-boot wizard (can also be done via web UI)
  2. Power on the appliance

Network Configuration​

The appliance ships with DHCP enabled. After boot:

  1. Find the appliance's IP address:
    • Check your DHCP server's lease table
    • Or connect a monitor -- the IP is displayed on the console
  2. Navigate to https://<appliance-ip>:443 in a browser
  3. Accept the self-signed certificate warning (temporary until TLS is configured)

First-Boot Wizard​

The setup wizard runs automatically when you first access the web UI:

  1. Admin Account -- Create the initial administrator (email, display name, password)
  2. License Activation -- Paste the license key provided by your account team (optionally provide a Portal API Token for automatic signature updates)
  3. Validation -- The system verifies the license signature, creates your environment, and configures default security policies
  4. Success -- Confirms your organization name, license tier, expiry, and max users, then redirects to the dashboard

Note: Network configuration (IP, DNS, TLS) is handled at the OS/appliance level before the web UI is accessible. Configure your static IP, DNS record, and TLS certificate (or reverse proxy) before navigating to the setup wizard.

Step 2: Connect Directory​

Active Directory / LDAP (Recommended for On-Prem)​

  1. Log into the Surface Security dashboard
  2. Navigate to Settings > Directory Sync > Add Source > Active Directory
  3. Configure connection:
    • LDAP URL: ldaps://dc01.yourcompany.com:636 (use LDAPS for encrypted connections)
    • Bind DN: CN=surfacesec-svc,OU=Service Accounts,DC=yourcompany,DC=com
    • Bind Password: The service account password
    • Base DN: DC=yourcompany,DC=com
    • User Filter: (&(objectClass=user)(objectCategory=person)) (default)
    • Group Filter: (objectClass=group) (default)
  4. Click Test Connection to verify LDAP connectivity
  5. Click Save

Hybrid: SCIM for Cloud + LDAP for On-Prem​

For organizations with both cloud and on-premises directories:

  1. Add an Active Directory source for on-prem users (LDAP pull)
  2. Add an Entra ID or Okta source for cloud-synced users (SCIM push)
  3. Both sources appear in the directory sync dashboard
  4. Users from each source are tagged with their origin

Manual Import​

If no directory integration is needed:

  1. Navigate to Users > Bulk Import
  2. Upload a CSV file with columns: email, displayName, department

Step 3: Select Groups​

  1. Navigate to Settings > Directory Sync
  2. Click Configure Groups on your Active Directory source
  3. Choose:
    • Sync All Groups -- syncs all groups found in AD
    • Select Specific Groups -- pick security groups or distribution lists
  4. Select the Identification Method:
    • sAMAccountName -- recommended for pure on-prem AD environments
    • UPN -- if users have UPN configured
    • Email (mail) -- if the mail attribute is populated
  5. Click Save and then Sync Now to pull groups

Step 4: Deploy Extension​

For the fastest path to first enrollment:

  1. Configure SSO at Settings > SSO
  2. Generate a magic link at Onboarding > Deploy method > Magic Link and click Generate
  3. Share the link with your team via Slack, email, or wiki

Users click the link, authenticate via SSO, and their extension enrolls automatically. Works on any device with an internet connection to your IdP, regardless of domain membership.

See the Enterprise extension deployment guide for more details.

Mass rollout (Group Policy)​

For larger orgs or AD-joined device management:

  1. In the Surface Security dashboard, go to Onboarding > Step 3
  2. Click Generate Configuration to create an enrollment token
  3. Select Group Policy and copy the policy JSON
  4. In Group Policy Management Console (gpmc.msc):
    • Edit a GPO linked to the OUs containing target devices
    • Navigate to Computer Configuration > Administrative Templates > Google Chrome > Extensions
    • Configure "Configure the list of force-installed apps and extensions"
    • Add the extension ID with update URL
    • Set managed storage configuration with the generated JSON
  5. Run gpupdate /force on target devices or wait for policy refresh

SCCM / MECM​

  1. Create a PowerShell script deployment using the provided deployment script
  2. Pass the Tenant ID, API Endpoint, and Extension ID as parameters
  3. Deploy to a device collection targeting your pilot group

Manual Installation​

For testing:

  1. Install the extension from the browser store (or load unpacked from the built extension)
  2. Click the extension icon
  3. Enter the API Endpoint, Tenant ID, and Enrollment Token
  4. Click Enroll Device

Step 5: Verify Enrollment​

  1. In the dashboard, go to Onboarding > Step 4
  2. Confirm devices appear in the enrollment table
  3. Navigate to a few websites from an enrolled device
  4. Verify events appear in the Dashboard within seconds
  5. Check Alerts for any detected security issues

Backup and Recovery​

Automated Backups​

The appliance automatically backs up:

  • PostgreSQL database (daily, retained for 30 days)
  • Configuration files
  • TLS certificates

Backups are stored on the secondary NVMe drive (Tier 1) or replicated across cluster nodes (Tier 2+).

Manual Backup​

  1. Navigate to Settings > Backup in the dashboard
  2. Click Create Backup to trigger an immediate backup
  3. Download the backup file for off-site storage

Recovery​

From backup drive:

  1. Connect the USB recovery drive (included in the box)
  2. Boot from the USB drive
  3. Select "Restore from backup"
  4. Choose the backup point to restore

Factory reset:

  1. Boot from the USB recovery drive
  2. Select "Factory Reset"
  3. Re-run the first-boot wizard

Troubleshooting​

Appliance not reachable​

  • Verify network connectivity (check link lights on the Ethernet port)
  • Confirm DNS resolves to the correct IP: nslookup surfacesec.yourcompany.com
  • Check that ports 443 and 80 (if using Let's Encrypt) are not blocked by firewall

LDAP connection failed​

  • Verify the LDAP URL is correct (use ldaps:// for port 636)
  • Confirm the service account has read permissions on the target OUs
  • Check that the AD server's certificate is trusted (for LDAPS)
  • Test with ldapsearch or PowerShell: Get-ADUser -Server dc01 -Filter *

Extension enrollment fails​

  • Verify the appliance is reachable from the device
  • Check the enrollment token hasn't expired
  • Ensure managed storage is applied (chrome://policy for Chrome, edge://policy for Edge)
  • Check the extension service worker console for detailed error messages

Slow performance​

  • Check appliance CPU/memory usage in Settings > System Health
  • Verify ClickHouse data retention TTLs are configured correctly
  • For Tier 1 (single node), ensure total endpoint count doesn't exceed 1,000

For cloud deployment, see Cloud Onboarding.