Directory Sync and SSO

Surface Security supports connecting multiple identity providers through a unified directory sync abstraction layer. This enables automated user provisioning, group-based policy management, and single sign-on.

Supported Directory Sources

Type	Protocol	Direction	Configuration
Microsoft Entra ID	SCIM 2.0	Push (IdP to Surface Security)	Auto-creates OAuth client
Okta	SCIM 2.0	Push (IdP to Surface Security)	Auto-creates OAuth client
Active Directory	LDAP	Pull (Surface Security to AD)	LDAP URL, bind DN, base DN
Google Workspace	Directory API	Pull (Surface Security to Google)	Service account key
Manual	N/A	Manual	CSV import or dashboard UI

Architecture

+---------------------------------------------------------------------+
|                        Identity Providers                            |
|  +----------------+  +----------------+  +------------------------+ |
|  | Entra ID       |  | Okta           |  | Active Directory       | |
|  | (SCIM Push)    |  | (SCIM Push)    |  | (LDAP Pull)            | |
+--+-------+--------+--+-------+--------+--+-------+----------------+-+
           |                    |                    |
           | SCIM 2.0          | SCIM 2.0           | LDAP
           v                    v                    v
+---------------------------------------------------------------------+
|                      Surface Security Backend                        |
|  +----------------+  +----------------+  +------------------------+ |
|  | SCIM API       |  | OAuth Token    |  | LDAP Connector         | |
|  | /scim/v2/*     |  | /oauth/token   |  | Scheduled Pull Sync    | |
+--+----------------+--+----------------+--+------------------------+-+

SCIM 2.0 Integration (Entra ID / Okta)

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

Step 1: Create a Directory Source

1. Navigate to Settings > Directory Sync in the admin 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 generates:
   • 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)

Step 2: Configure Entra ID

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

2. Select Provisioning > Mode: Automatic

3. Enter the SCIM Endpoint URL and OAuth credentials

4. Click Test Connection to verify

5. Map attributes:

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

6. Enable group provisioning under Mappings

7. Map group attributes:

   Azure AD Attribute	SCIM Attribute
   displayName	displayName
   objectId	externalId
   members	members

8. Start initial provisioning cycle

Step 2 (Alternative): Configure Okta

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

LDAP Integration (Active Directory)

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 (use LDAPS for encrypted connections)
   • Bind DN: CN=surfacesec-svc,OU=Service Accounts,DC=yourcompany,DC=com
   • Bind Password: Service account password
   • Base DN: DC=yourcompany,DC=com
   • User Filter: (&(objectClass=user)(objectCategory=person)) (default)
   • Group Filter: (objectClass=group) (default)
3. Click Test Connection to verify LDAP connectivity
4. Configure group filtering if needed
5. Click Save and then Sync Now

LDAP sources use scheduled pull sync. Surface Security queries your AD at regular intervals to detect changes.

Google Workspace Integration

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

Hybrid Directory Configuration

Organizations with both cloud and on-premises directories can connect multiple sources simultaneously:

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

Group Filtering

Each directory source supports selective group sync:

• Sync All Groups -- automatically syncs all groups from the source
• Select Specific Groups -- pick individual groups to sync

Configure group filtering on each source via Settings > Directory Sync > Configure Groups.

Group-Based Policy Management

Policies can be assigned to groups synced from your identity provider. Users inherit policies from all groups they belong to.

Assigning Policies to Groups

1. Navigate to Policies in the admin dashboard
2. Select a policy
3. Under Group Assignment, add the groups that should receive this policy

Policy Resolution

When a user belongs to multiple groups with different policies, the most restrictive wins:

Setting	Resolution Rule
Mode	block > warn > learning (highest restriction wins)
Denied Domains	Union of all policies (if ANY policy blocks a domain, it is blocked)
Allowed Domains	Intersection (domain must be allowed by ALL policies)
Features	AND logic (enabled only if ALL policies enable it)

Example: A user is in Group A and Group B:

• Group A policy: mode=warn, denied=[evil.com]
• Group B policy: mode=block, denied=[phishing.com]

Effective policy for that user:

• Mode: block (most restrictive)
• Denied: [evil.com, phishing.com] (union)

SSO Overview

Surface Security supports single sign-on for admin dashboard access. SSO configuration is managed through the Settings > Authentication page in the admin dashboard.

Supported SSO protocols:

• SAML 2.0 -- for enterprise IdPs (Entra ID, Okta, ADFS, Ping Identity)
• OpenID Connect (OIDC) -- for modern IdPs and custom OAuth 2.0 providers

SSO for admin access is separate from the directory sync used for employee provisioning. You can use SCIM for employee sync while using SAML for admin SSO, or combine them as needed.

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)

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)