Security Policies

Surface Security uses configurable security policies to control how the browser extension responds to credential events. Policies define rules that match against domains, credential behaviors, and authentication patterns, then take an action (allow, warn, or block).

Policy Actions

Action	Behavior
Allow	The credential event proceeds without interruption
Warn	A warning modal is displayed to the user; they may choose to proceed or cancel
Block	A block modal is displayed and the credential submission is prevented entirely

Policy Structure

Each policy contains:

• Name -- A descriptive label (e.g., "Block known phishing domains")
• Description -- Purpose of the policy
• Priority -- Numeric priority; lower numbers are evaluated first
• Enabled -- Whether the policy is active
• Rules -- One or more matching rules with conditions and an action

Policy Rules

Rules define the conditions under which a policy applies. Each rule includes:

• Domain match -- Which domains the rule applies to (exact match, wildcard, or regex)
• Condition -- The credential event condition (e.g., password reuse detected, breached password, phishing signal)
• Action -- The action to take when the rule matches (allow, warn, or block)

Extension Modes

Tenants can configure an overall extension mode that sets the baseline behavior:

Mode	Description
Learning	Events are collected but no warnings or blocks are shown to users; used during initial rollout
Warn	Users receive warning modals for policy matches but can proceed
Block	Users are blocked from submitting credentials that match policy rules

The extension mode acts as a floor. If the extension mode is set to "learning," no policies will trigger warn or block actions regardless of their configuration.

Group-Based Policies

Policies can be assigned to groups (synced from identity providers via SCIM or directory sync). Users inherit policies from all groups they belong to.

Resolution Logic: Most Restrictive Wins

When a user belongs to multiple groups with different policies, the effective policy is resolved using "most restrictive wins" logic:

Property	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 of all policies (must be allowed by ALL policies)
Features	AND logic (a feature is enabled only if ALL policies enable it)

Example

If a user belongs to two groups:

• Engineering policy: warn on *.example.com, allow internal.example.com
• Contractors policy: block on *.example.com, allow internal.example.com, allow docs.example.com

The effective policy for a user in both groups:

• Mode: block (most restrictive)
• Denied domains: union = *.example.com
• Allowed domains: intersection = internal.example.com (only domain allowed by both)

Managing Policies

Create a Policy

Navigate to Policies in the admin dashboard and click Create Policy. Define the name, priority, rules, and assign to groups.

API

Policies can also be managed via the Admin API:

• GET /api/v1/admin/policies -- List all policies
• POST /api/v1/admin/policies -- Create a new policy
• PUT /api/v1/admin/policies/{id} -- Update a policy
• DELETE /api/v1/admin/policies/{id} -- Delete a policy

See the Admin API reference for full request/response details.

Policy Sync

Policies are synced to browser extensions via the GET /api/v1/ext/policies endpoint. The extension periodically polls this endpoint to receive updated policy rules. Changes to policies take effect on the next sync cycle.