Cloud Client Onboarding Guide

This guide walks you through connecting Surface Security to your cloud identity provider and deploying the browser extension to your workforce.

Prerequisites

Before beginning onboarding, ensure you have:

• Surface Security tenant URL (e.g., https://surfacesec.yourcompany.com)
• Admin access to the Surface Security dashboard
• Identity provider admin access (Entra ID, Okta, or Google Workspace)
• MDM/GPO access (for managed extension deployment) -- or permission to install browser extensions manually

Step 1: Connect Your Directory

Surface Security supports multiple identity providers for user and group synchronization.

Option A: Entra ID / Okta (SCIM Push)

SCIM 2.0 push provisioning lets your identity provider automatically send user and group changes to Surface Security.

1. Navigate to Settings > Directory Sync in the Surface Security dashboard
2. Click Add Source and select Microsoft Entra ID or Okta
3. Enter a descriptive name (e.g., "Production Entra ID")
4. Surface Security will generate:
   • SCIM Endpoint URL -- enter this as the Tenant URL in your IdP
   • OAuth Client ID and Client Secret -- use these for authentication
5. Copy these credentials (the client secret is shown only once)

Entra ID Configuration:

1. In Azure Portal, go to Enterprise Applications > Create new

2. Select Provisioning > Mode: Automatic

3. Enter the SCIM Endpoint URL and OAuth credentials from step 4

4. Click Test Connection to verify

5. Map attributes:

   Azure AD Attribute	SCIM Attribute
   userPrincipalName	userName
   displayName	displayName
   mail	emails[type eq "work"].value
   objectId	externalId

6. Enable group provisioning under Mappings

7. Start initial provisioning cycle

Okta Configuration:

1. In Okta Admin Console, go to Applications > Add
2. Choose SCIM 2.0 Test App (OAuth Bearer Token)
3. Enter the SCIM Endpoint URL as the Base URL
4. For authentication, obtain a token using the OAuth Client ID/Secret
5. Enable Push Groups to sync group membership

Option B: Active Directory (LDAP Pull)

For on-premises Active Directory without cloud federation.

1. Navigate to Settings > Directory Sync > Add Source > Active Directory
2. Configure connection:
   • LDAP URL: ldaps://dc01.yourcompany.com:636
   • Bind DN: CN=surfacesec-svc,OU=Service Accounts,DC=yourcompany,DC=com
   • Bind Password: Service account password
   • Base DN: DC=yourcompany,DC=com
3. Click Test Connection to verify LDAP connectivity
4. Configure user/group filters if needed
5. Click Save and then Sync Now

Option C: Google Workspace (Directory API)

1. Navigate to Settings > Directory Sync > Add Source > Google Workspace
2. Configure:
   • Domain: yourcompany.com
   • Service Account Email: From your Google Cloud project
   • Service Account Key: Upload the JSON key file
3. Ensure domain-wide delegation is enabled for the service account
4. Click Test Connection and Save

Option D: Manual / CSV Import

For small deployments or environments without a supported IdP:

1. Navigate to Users in the dashboard
2. Click Bulk Import and upload a CSV with columns: email, displayName, department
3. Or use Add User to create users individually

Step 2: Select Groups and Identification Method

After connecting your directory source:

1. Navigate to Settings > Directory Sync
2. Click Configure Groups on your connected source
3. Choose sync mode:
   • Sync All Groups -- automatically syncs all groups from the source
   • Select Specific Groups -- pick individual groups to sync
4. Select the Identification Method:
   • Email (mail) -- recommended for most environments
   • UPN -- use when email doesn't match UPN
   • sAMAccountName -- for legacy AD environments
5. Click Save

Groups can be viewed and managed on the dedicated Groups page.

Step 3: Deploy the Extension

Quickstart (recommended)

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. No MDM required.

See the Enterprise extension deployment guide for more details.

Mass rollout

For larger orgs that prefer to push the extension via MDM, use one of the following methods for centralized, zero-touch deployment:

Microsoft Intune

1. In Surface Security, go to Onboarding > Step 3 > Select Microsoft Intune
2. Click Generate Configuration to create an enrollment token
3. Copy the generated managed configuration JSON
4. In Intune admin center:
   • Go to Devices > Configuration profiles > Create
   • Add Chrome/Edge extension force-install settings
   • Paste the managed configuration JSON
   • Assign to your target user groups

Windows Group Policy

1. In Surface Security, go to Onboarding > Step 3 > Select Group Policy
2. Generate and copy the extension policy JSON
3. In Group Policy Management:
   • Edit a GPO linked to target OUs
   • Navigate to Computer Configuration > Administrative Templates > Google Chrome > Extensions
   • Set "Configure the list of force-installed apps and extensions"
   • Add the extension ID and configuration

Chrome Browser Cloud Management (CBCM)

1. In Surface Security, go to Onboarding > Step 3 > Select Chrome CBCM
2. Generate and copy the configuration
3. In Google Admin Console:
   • Go to Devices > Chrome > Apps & extensions
   • Add the extension and set to Force install
   • Paste the managed configuration

Manual Installation

For testing or small deployments:

1. Install the Surface Security extension from your browser's extension store
2. Click the extension icon
3. Enter the API Endpoint, Tenant ID, and Enrollment Token from the dashboard
4. Click Enroll Device

Step 4: Verify Enrollment

1. Navigate to Onboarding > Step 4 in the dashboard
2. Check the status cards:
   • Synced Users -- total users from directory sync
   • Enrolled Devices -- devices that have completed enrollment
   • Directory Sources -- configured identity providers
3. Recent device enrollments will appear in the table below
4. Navigate to a few websites on an enrolled device -- events should appear in the Dashboard within seconds

Test Enrollment

Before rolling out to all users:

1. Deploy the extension on your own device first
2. Navigate to several websites and verify events appear
3. Check the Alerts page for any detected security issues
4. Verify that policies are being enforced as expected
5. Once confirmed, proceed with broader deployment

Troubleshooting

SCIM provisioning not working

• Verify the SCIM endpoint URL and OAuth credentials in your IdP
• Check Settings > Directory Sync for source status and error messages
• Ensure the enterprise app in your IdP has provisioning enabled
• Check the Surface Security audit log for SCIM request details

Users not appearing after sync

• Confirm the directory sync status shows "Active"
• Click Sync Now to trigger a manual sync
• Verify users are in the synced groups (if specific groups are configured)

Extension not enrolling

• Check the enrollment token hasn't expired (tokens are valid for 7 days)
• Verify the API endpoint is reachable from the device
• Check browser developer tools (extension service worker) for error messages
• For managed deployment, ensure managed storage configuration is applied

Devices showing as offline

• Check that the device has network connectivity to the Surface Security backend
• Verify mTLS certificates haven't been revoked
• Restart the browser to trigger a fresh connection

---

For on-premises appliance deployment, see On-Premises Onboarding.