Design: 1Password Integration for Google SSO Authentication

Problem

Scout cannot test websites that use Google SSO (or similar OAuth providers) for authentication. This is a critical gap because:

Google blocks automated browsers — Google actively detects Playwright, Puppeteer, and other automation tools during the OAuth login flow and refuses to proceed
No TOTP/MFA support — Scout's current credential types (basic_auth, api_key) have no mechanism for time-based one-time passwords or multi-factor authentication challenges
OAuth redirects are complex — SSO flows involve multi-step redirects across domains (app → Google → consent → callback) that are fragile to automate
Existing workarounds are unreliable — Approaches like Stably.ai's TOTP extraction (extracting the OTP secret and generating codes programmatically) are easily blocked by Google's evolving bot detection

Impact: Any customer whose target application uses "Sign in with Google" (or Microsoft, Okta, etc.) cannot use Scout to test authenticated flows — a significant portion of modern web applications.

Goal

Integrate 1Password as Scout's primary credential store for SSO-protected websites, enabling Scout to:

Resolve credentials + TOTP at runtime from the customer's 1Password vault via the official SDK — no secrets stored in Scout's database
Handle Google SSO login flows by combining 1Password credential resolution with Browserbase stealth browsers (Phase 1) and zero-knowledge Agentic Autofill (Phase 2)
Provide a seamless customer experience — most target customers already use 1Password, so setup is a one-time service account configuration per project
Maintain security — credentials are resolved just-in-time, never persisted, and in Phase 2 never even enter the LLM context

Success criteria: A Scout execution can successfully log in to a Google SSO-protected website and proceed with testing, with the customer only needing to configure their 1Password vault reference once.

Sequence Diagrams

Phase 1: 1Password SDK Credential Resolution

sequenceDiagram
    participant Agent as Scout Agent
    participant 1P as 1Password Vault
    participant Browser as Browser
    participant Google as Google SSO

    Agent->>1P: Resolve username, password, TOTP
    1P-->>Agent: Credentials (in-memory only)
    Agent->>Browser: Navigate to target app
    Browser->>Google: Redirect to login
    Agent->>Browser: Fill credentials + TOTP
    Browser->>Google: Submit
    Google-->>Browser: Auth success
    Agent->>Agent: Continue testing

Phase 2: Browserbase + 1Password Agentic Autofill (Zero-Knowledge)

sequenceDiagram
    participant User as Customer
    participant 1P as 1Password App
    participant BB as Browserbase + 1Password Extension
    participant Google as Google SSO
    participant Agent as Scout Agent

    Agent->>BB: Navigate to target app
    BB->>Google: Redirect to login
    BB->>1P: Request autofill (E2E encrypted)
    1P->>User: Approve sign-in?
    User->>1P: Approve
    1P->>BB: Inject credentials + TOTP (E2E encrypted)
    BB->>Google: Submit (filled by extension)
    Google-->>BB: Auth success
    Agent->>Agent: Continue testing (never saw credentials)

Context

Most Scout customers already use 1Password. By integrating 1Password as the primary credential store, Scout can leverage existing customer infrastructure without requiring new tool adoption.

Decision: Browserbase-first approach, leveraging the existing browserbase browser provider in Scout. Human-in-the-loop approval for login is acceptable.

Current Credential Architecture

Scout supports two credential types stored in ProjectCredential.payload (JSON):

Type	Fields	Usage
`basic_auth`	`username`, `password`	Injected as XML into LLM prompt, agent fills forms
`api_key`	`secret`	Injected as XML into LLM prompt

Flow: DB → Execution Claim → XML in LLM prompt → Agent uses browser tools to fill forms.

Key files:

Component	Path
Credential types	`packages/scout-common/src/routes/scout-webapp/project/project.credential.ts`
Prisma schema	`packages/scout-webapp/prisma/schema.prisma` (lines 367-380)
Agent context formatting	`packages/scout-agent/src/mastra/prompts/agent-context.ts`
Execution claim	`packages/scout-webapp/src/app/api/v1/executions/[id]/claim/route.ts`
Working memory	`packages/scout-agent/src/models/working-memory.ts`
Browserbase integration	`packages/scout-agent/src/legacy/services/browser/browserbase.ts`
Browser manager	`packages/scout-agent/src/services/device/browser/browser-manager.ts`
UI components	`packages/scout-webapp/src/components/project/credential/`

Why Not Just Username/Password?

Google SSO has two barriers for automated browsers:

Bot detection — Google actively detects Playwright/Puppeteer and blocks login attempts
Multi-factor auth — TOTP/push notifications add steps that basic credentials can't handle

Stably.ai's approach (extract TOTP secret, generate OTP codes programmatically) is fragile and easily blocked by Google.

Recommended Approach: Two-Phase Rollout

Phase 1: 1Password SDK Integration (Build Now)

Use @1password/sdk (JavaScript) to resolve credentials at runtime. Works with all Scout browser providers (AWS, Browserbase, local).

New credential type: 1password_vault_ref

{
  type: "1password_vault_ref",
  serviceAccountToken: string,       // encrypted 1Password service account token
  secretReferences: {
    username: "op://vault/item/username",
    password: "op://vault/item/password",
    totp?: "op://vault/item/otp?attribute=otp"   // optional, for MFA
  }
}

Runtime flow:

Execution starts
  → scout-agent resolves credentials via @1password/sdk (just-in-time)
  → TOTP resolved right before form fill (30-sec validity)
  → Credentials formatted as basic_auth equivalent for the agent
  → Agent fills login forms using browser tools
  → Credentials exist only in memory, never persisted

Files to modify:

File	Change
`packages/scout-common/.../project.credential.ts`	Add `1password_vault_ref` to credential payload union
`packages/scout-agent/package.json`	Add `@1password/sdk` dependency
`packages/scout-agent/.../agent-context.ts`	Resolve 1Password refs before formatting; handle TOTP timing
`packages/scout-agent/.../working-memory.ts`	Store resolved (transient) credentials in working memory
`packages/scout-webapp/.../credential/`	New UI form for 1Password vault reference setup
`packages/scout-webapp/.../claim/route.ts`	Pass 1Password credential type through (NOT resolved — resolution happens in agent)

Key design decisions:

Resolution happens in scout-agent, NOT webapp — service account token stays server-side
TOTP resolved just-in-time — called right before form fill, not at claim time
Service account token encrypted at rest — use existing JSON payload field, encrypt the token
No credential caching — resolve fresh each execution for security

Phase 2: Browserbase + 1Password Agentic Autofill (When GA)

Upgrade from SDK-based credential resolution to zero-knowledge Agentic Autofill. Credentials never enter Scout or the LLM at all.

Architecture:

1Password app (user's device)
  ↔ E2E encrypted channel (Noise framework)
  ↔ Browserbase cloud browser (with 1Password extension)
  → Credentials injected directly into the login page
  → Scout/LLM never sees credentials

What changes from Phase 1:

For projects using browserbase provider: skip SDK resolution, let Agentic Autofill handle it
User gets a 1Password notification to approve each login
TOTP handled automatically by 1Password extension
formatCredentials() excludes 1Password refs from LLM prompt (credentials not needed in context)

Why this matters for Google SSO:

Browserbase stealth browsers have better fingerprinting than raw Playwright, reducing bot detection
1Password extension fills the form (not Playwright fill()), so Google sees human-like interaction patterns
E2E encryption means credentials never transit through Scout infrastructure

Files to modify (incremental on Phase 1):

File	Change
`packages/scout-agent/.../browserbase.ts`	Enable 1Password extension in `sessions.create()`
`packages/scout-agent/.../agent-context.ts`	Instruct agent to "click sign-in and wait for autofill" instead of manual fill
`packages/scout-agent/.../browser-manager.ts`	Pass credential context to Browserbase initialization

Dependency: 1Password Agentic Autofill exits Early Access and becomes generally available. Currently Browserbase-exclusive.

Existing Code to Reuse

Credential discriminated union — project.credential.ts: extend with new type
formatCredentials() — agent-context.ts: add 1Password resolution step before formatting
createBrowserbaseSession() — browserbase.ts: extend browserSettings for extension config
Credential UI components — credential-dialog.tsx: add new form variant
Credential CRUD hooks — use-credential.ts: reuse existing mutations

UX Flow for Customers

Setup (one-time per project)

Customer creates a 1Password Service Account and grants it vault access
In Scout project settings → Credentials → "Add 1Password Credential"
Customer enters:
- Service Account Token
- Secret references: op://vault/item/username, op://vault/item/password, op://vault/item/otp (optional)
- Label and notes (e.g., "Google SSO for staging")
Scout validates the references by doing a test resolve

During test execution

Phase 1: Agent resolves credentials via SDK, fills login forms, handles TOTP
Phase 2 (Browserbase): Agent clicks "Sign in", 1Password autofills, user approves on phone

Google SSO Mitigation Strategies

Even with 1Password resolving credentials + TOTP, Google may still block the automated browser in Phase 1. Mitigation:

Strategy	Phase	Effectiveness
Browserbase stealth browsers (better fingerprinting)	1	Medium
1Password Agentic Autofill (extension fills forms, not Playwright)	2	High
Agent fallback reporting ("Google SSO blocked")	1	Diagnostic

Phase 2 is the real unlock for Google SSO — the combination of stealth browsers + extension-based form filling significantly reduces detection risk.

Verification Plan

Phase 1

Unit tests: Mock @1password/sdk client, verify credential resolution and TOTP timing
Integration test: Create a test 1Password vault with a test login, verify end-to-end resolution
Agent test: Run a Scout execution against a site with username/password + TOTP, confirm login
UI test: Verify credential creation form validates op:// references and masks the service account token

Phase 2

Browserbase session: Verify 1Password extension is loaded in Browserbase session
E2E flow: Run Scout execution with Browserbase provider against Google SSO site
Approval flow: Verify 1Password notification appears and approval completes login

Open Items / Future Considerations

Service account token encryption: Implement encryption for the payload JSON field (noted as existing TODO in data-modeling.md)
Multi-provider support: Consider Bitwarden, LastPass integrations for customers not on 1Password
Session caching: Add browser_session credential type as an optimization for unattended/scheduled runs (store Playwright storageState after first successful login)
1Password Agentic Autofill GA timeline: Monitor for general availability announcement

phatpham-katalon/1 Password SSO Authentication Solution.md

Select an option

No results found