Onboarding
The Onboarding page walks you from a freshly installed Surface Security deployment to a fleet of enrolled browsers. It is a six-step wizard that connects your identity provider, prepares end-to-end encryption, deploys the browser extension, and confirms that devices are reporting in. You reach it from the highlighted Onboarding entry at the top of the dashboard sidebar.
The wizard is resumable and order-flexible: you can click any step in the progress rail to jump around, and steps that are already satisfied (for example, a directory source that already exists) are detected automatically and marked complete. Steps you skip can always be finished later from the regular Settings pages — the wizard is a guided front door, not the only door.
[SCREENSHOT PLACEHOLDER: The Onboarding page showing the six-step progress rail (Connect Directory, Select Groups, Add First User, E2E Encryption, Deploy Extension, Verify Enrollment) with Step 1 active]
Before the wizard: the TLS certificate gate
On a new deployment the console is served with a self-signed TLS certificate. Until a trusted certificate is installed, opening the dashboard redirects you to the Configure TLS Certificate page.
- Paste your Certificate (PEM) and Private Key (PEM) and click Upload & Configure. The gateway is reconfigured with the new certificate and the console reloads once it is back.
- The private key is used only to configure the gateway and is stored in the deployment's own volume or Kubernetes Secret — it is never stored in the database.
- You can click Skip for now to continue to Onboarding with the self-signed certificate. The skip lasts for your current browser session; browsers will keep showing security warnings until a trusted certificate is installed, and the onboarding checklist will not count as fully complete.
[SCREENSHOT PLACEHOLDER: The Configure TLS Certificate page with the Certificate (PEM) and Private Key (PEM) fields, the self-signed certificate warning banner, and the Skip for now link]
Step 1 — Connect Directory
Choose the identity provider that owns your user population:
| Option | How it syncs |
|---|---|
| Microsoft Entra ID | SCIM 2.0 push provisioning from Azure AD / Entra ID |
| Okta | SCIM 2.0 push provisioning from Okta |
| Active Directory | LDAP pull sync from on-premises AD |
| Google Workspace | Directory API sync from Google Workspace |
| Manual / CSV | Import users manually or via CSV file |
Give the connection a Source Name (for example, "Production Entra ID") and click Connect Source. The Advanced Setup button takes you to the full directory-sync settings page for provider-specific credentials and sync options — see the Directory Sync guide for the detailed per-provider walkthrough.
If a source already exists, it is listed under Connected Sources with its sync status, and you can continue directly to Step 2. You can also choose Skip for now — I'll set up directory sync later and add users manually in Step 3.
Step 2 — Select Groups
Under Group Sync Settings, decide which directory groups Surface Security should import. Groups determine policy assignment for users.
- Sync All Groups (default) imports every group from the source.
- Turn the toggle off to pick individual groups from the list, with member counts shown per group.
Under Identification Method, choose how synced users are matched to the identities the browser extension observes:
- Email (mail) — match users by their email address
- UPN — match by User Principal Name
- sAMAccountName — match by Windows login name
Step 3 — Add First User
Create at least one user before deploying the extension. Surface Security binds the first enrollment token to this user's email and waits for their device to report in — this gives you a known-good test subject for Step 6.
The form on the left adds a user directly; the Pending users panel on the right shows users waiting for a device to claim them. If your directory sync has already populated users, the step is satisfied and you can continue.
Step 4 — E2E Encryption
Upload a CA certificate and private key to enable end-to-end encrypted communication between the browser extensions and the server. The CA signs individual device certificates during extension enrollment.
Two important notes shown on the page:
- Use a dedicated certificate. This CA must be separate from the TLS certificate that serves HTTPS traffic, so your web server credentials stay isolated from device enrollment.
- The private key is encrypted before storage and never exposed via the API.
If you do not have a CA yet, the page includes ready-to-copy OpenSSL commands to generate a self-signed CA. Once uploaded, the page shows the configured CA's subject, issuer, expiry, and fingerprint; you can manage it later under Settings > General. This step can be skipped with Skip for Now, but extensions cannot complete encrypted enrollment while your deployment has E2E encryption enabled without a CA.
[SCREENSHOT PLACEHOLDER: Step 4 (E2E Encryption) showing the CA Certificate and CA Private Key PEM fields, the "Use a dedicated certificate for this" notice, and the OpenSSL generation snippet]
Step 5 — Deploy Extension
This step generates everything needed to push the extension to employee browsers.
Configure SSO Enrollment (optional, recommended for MDM). When you push the extension via Intune, GPO, or Jamf, devices enroll by signing in through your identity provider — no per-user tokens to distribute. Two one-time tasks: connect your IdP under Settings > SSO, and register a second redirect URI (shown on the page with a copy button) in your IdP application alongside the dashboard one. One URI covers the whole deployment.
Generate Deployment Configuration. Optionally pick a user under Assign to Employee to bind the enrollment token to a specific person, or leave it empty for a general-use token, then click Generate Configuration.
Choose Deployment Method. Five options, each producing a tailored, copyable configuration:
- Magic Link (recommended, where enabled on your deployment) — generate one tenant-scoped link and share it via Slack, email, or your wiki; users click it and sign in with SSO to enroll. Requires SSO to be configured first. The panel tracks clicks and completed enrollments per link and lets you revoke links. Do not post magic links in public channels.
- Microsoft Intune — the managed-storage keys the extension consumes, plus step-by-step instructions for the force-install profile and the policy profile.
- Group Policy — a PowerShell script that safely appends the extension to the Chrome and Edge force-install lists and writes the per-extension policy values, including the device hostname so each endpoint reports its machine name with no native agent.
- Chrome CBCM — the managed-policy JSON to paste into Chrome Browser Cloud Management, with Admin Console steps.
- Manual Install — the API Endpoint, Tenant ID, Enrollment Token, and (when E2E is configured) CA Certificate that an employee enters in the extension after installing it from the browser store.
For Intune and Group Policy, a macOS Configuration Profile (.mobileconfig) is also generated for Jamf Pro, Intune, Mosyle, Kandji, or any MDM that accepts Apple profiles. The page additionally documents the private-browsing policies for Chrome and Edge so force-installed extensions keep coverage in incognito/InPrivate windows.
The full deployment reference, including per-platform details, lives in the Extension Deployment guide.
[SCREENSHOT PLACEHOLDER: Step 5 (Deploy Extension) with the five deployment method cards (Magic Link, Microsoft Intune, Group Policy, Chrome CBCM, Manual Install) and a generated configuration below]
Step 6 — Verify Enrollment
The final step confirms the pipeline end to end:
- Three counters: Synced Users, Enrolled Devices, and Directory Sources.
- A Recent Device Enrollments table (device, user, status, last seen) with a Refresh button — devices appear here within seconds of enrolling.
- A Test Enrollment checklist: install the extension in your own browser, enter the enrollment details from Step 5, browse a few sites, and confirm events and alerts appear in the dashboard.
Click Go to Dashboard when you are done.
[SCREENSHOT PLACEHOLDER: Step 6 (Verify Enrollment) showing the Synced Users / Enrolled Devices / Directory Sources counters and the Recent Device Enrollments table with one active device]
When the Onboarding entry disappears
The Onboarding sidebar entry is shown only to Super Admin and Admin roles, and only while setup is incomplete. The platform tracks completion automatically across these signals:
- An admin account exists
- A trusted TLS certificate is installed
- The E2E encryption CA is uploaded
- At least one directory source is healthy
- At least one policy is saved
- An enforcement mode beyond learning has been chosen in a policy
- A device has enrolled within the last 7 days
Once every signal is satisfied, the Onboarding entry drops out of the sidebar so navigation stays focused on day-to-day operations. Everything the wizard configures remains editable from the Settings pages.
The guided product tour
Admins also get a Take the Tour button at the bottom of the sidebar. It launches a guided, section-by-section tour of the console — including the onboarding wizard itself — and remembers your progress: after the first section the button changes to Resume Tour with the name of the next section. The button disappears once all tour sections are completed. The tour is available to Super Admin and Admin roles.
[VIDEO PLACEHOLDER: A short capture of clicking Take the Tour and stepping through the first tour section, ending with the Resume Tour button state]
Troubleshooting
The dashboard keeps redirecting me to the TLS page. No trusted certificate is installed yet. Upload one, or click Skip for now (the skip lasts for the current browser session).
Step 4 shows "Certificate Service Unavailable". The certificate management service is not configured on the backend. The page lists the exact remediation: generate an encryption key, set it in the deployment environment, and restart the backend. Your platform team performs this — see the deployment guides under Getting Started.
Magic Link is not offered in Step 5. Magic-link enrollment is a deployment-level capability and also requires SSO to be configured. Configure a provider under Settings > SSO first.
No devices appear in Step 6. Confirm the extension was actually installed (force-install can take a browser restart), that the enrollment details match the generated configuration, and that the CA certificate was provided if E2E encryption is enabled. The warning banner on Step 5 flags the case where E2E is enabled but no CA is uploaded — extensions cannot enroll in that state.