fix: Enable automatic Playwright browser driver download for SAML authentication

[osterman]

what

Fixes SAML authentication failing with "please install the driver (v1.47.2) and browsers first" error when download_browser_driver: true is configured.

why

Root cause: The DownloadBrowser flag was set on saml2aws IDPAccount config but NOT on LoginDetails, which is what saml2aws actually checks when deciding whether to download drivers.

Additionally, the code was using incorrect Playwright cache directory paths (ms-playwright-go instead of ms-playwright), causing driver detection to fail.

Changes

Code Changes

• Set LoginDetails.DownloadBrowser in createLoginDetails() to match shouldDownloadBrowser() logic
• Corrected Playwright cache directory paths from ms-playwright-go to ms-playwright (actual playwright-go location)
• Enhanced driver detection to verify actual browser binaries exist (not just empty version directories)

Testing

• Added comprehensive integration test that downloads real Chromium drivers (~140 MB) and validates installation
• Unit tests verify LoginDetails.DownloadBrowser is set correctly across all scenarios
• Driver detection tests verify empty directories don't register as valid installations

Documentation

• Removed broken manual installation command (go run playwright install)
• Added warning about manual installation requiring advanced knowledge of playwright-go internals
• Clarified cache directory locations and why PATH is not required
• Emphasized download_browser_driver: true as the recommended approach

references

• Fixes the issue where SAML authentication with download_browser_driver: true still fails
• Related to playwright-go embedded library behavior vs standalone playwright CLI tool
• Playwright cache locations: https://playwright.dev/docs/browsers#managing-browser-binaries

Summary by CodeRabbit

• New Features

  • Automatic Playwright browser driver downloads for AWS SAML auth (opt-in via download_browser_driver); new config options browser_type and browser_executable_path; improved cross-platform driver detection and XDG-compliant storage/symlink handling.
  • Atmos logging now captures and forwards Playwright/logrus output via a new logging adapter.

• Documentation

  • Expanded docs: auto-download workflow, manual-install guidance, custom browser config, platform cache paths, examples, and opt-in instructions for heavy integration tests.

• Tests

  • Added unit and integration tests for driver detection, download/install flow, storage/symlink behavior, and log adapter.

[github-actions[bot]]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[coderabbitai[bot]]

📝 Walkthrough

Walkthrough

Adds Playwright-based browser driver detection and optional auto-download to the AWS SAML provider, exposes browser fields in the schema, introduces a logrus→Atmos adapter, adds unit/integration tests and docs, and enables CI opt-in for Playwright integration.

Changes

Cohort / File(s)	Summary
Dependency Updates go.mod	Promoted github.com/playwright-community/playwright-go and github.com/sirupsen/logrus to direct requirements; removed some indirect entries.
Core SAML Driver Integration pkg/auth/providers/aws/saml.go	Added XDG/LOCALAPPDATA-aware Playwright driver discovery, conditional auto-download logic, BrowserType/BrowserExecutablePath propagation, DownloadBrowser propagation, XDG storage setup and symlink creation, browser executable validation, and logrus forwarding.
Schema Extension pkg/schema/schema_auth.go	Added exported BrowserType and BrowserExecutablePath fields to Provider.
Errors errors/errors.go	Added exported sentinel ErrInvalidBrowserExecutable.
Logrus Adapter pkg/logger/logrus_adapter.go, pkg/logger/logrus_adapter_test.go	New adapter routing logrus output into Atmos logger plus tests for Write, formatter options, and level mapping; public ConfigureLogrusForAtmos() added.
SAML Unit Tests & Detection pkg/auth/providers/aws/saml_test.go, pkg/auth/providers/aws/saml_driver_detection_test.go	Tests updated/added for DownloadBrowser scenarios, browser config propagation, shouldDownloadBrowser behavior; macOS Playwright cache path constants updated (ms-playwright-go → ms-playwright).
Driver Download Integration Tests pkg/auth/providers/aws/saml_driver_download_integration_test.go	New integration tests exercising Playwright driver download flow, config mapping and consistency across IDPAccount/LoginDetails (guarded by env flag).
Storage & Symlink Tests pkg/auth/providers/aws/saml_storage_test.go	New tests for XDG cache directory creation, symlink creation/idempotence, and storage setup behavior.
CI / Test Docs .github/workflows/test.yml, tests/README.md	Added RUN_PLAYWRIGHT_INTEGRATION env var to CI workflow and documented heavy integration test opt-in and Chromium download behavior.
User Docs & Design website/docs/cli/commands/auth/usage.mdx, docs/prd/saml-browser-driver-integration.md	Documented new driver and download_browser_driver options, auto-download workflow, custom browser fields, platform cache paths, and testing/design guidance.

Sequence Diagram(s)

sequenceDiagram
    %% Styling hint: boxes are conceptual, colors for emphasis avoided
    participant User
    participant Atmos
    participant SAML as "AWS SAML Provider"
    participant Playwright
    participant Cache as "XDG / LOCALAPPDATA Cache"

    User->>Atmos: start auth (SAML provider)
    Atmos->>SAML: Authenticate(config)
    SAML->>SAML: ConfigureLogrusForAtmos()
    SAML->>SAML: createSAMLConfig() / createLoginDetails()

    alt shouldDownloadBrowser == true
        SAML->>Cache: probe platform cache for drivers
        alt no drivers found
            SAML->>Playwright: download & install browser
            Playwright->>Cache: populate cache
        else drivers found
            Cache-->>SAML: return driver paths
        end
    end

    SAML->>Playwright: launch browser (BrowserType / ExecutablePath)
    Playwright-->>SAML: browser session (SAML capture)
    SAML-->>Atmos: credentials
    Atmos-->>User: auth success

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

• Review focus:
  • XDG and Windows LOCALAPPDATA resolution, symlink creation/replacement, and permission handling in pkg/auth/providers/aws/saml.go.
  • Correct propagation and serialization of BrowserType, BrowserExecutablePath, and DownloadBrowser across schema, config, and creds.
  • Logrus adapter behavior and global logrus configuration side effects.
  • Integration tests guarded by RUN_PLAYWRIGHT_INTEGRATION and filesystem/environment isolation in tests.

Possibly related PRs

• cloudposse/atmos#1655 — Overlaps with AWS SAML provider changes (driver detection, schema fields, tests).

Suggested reviewers

• aknysh

Pre-merge checks and finishing touches

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly addresses the main purpose of the PR: enabling automatic Playwright browser driver downloads for SAML authentication, which aligns with the core fix described in the objectives.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment
• [ ] Commit unit tests in branch saml-driver-install

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[mergify[bot]]

[!IMPORTANT]

Cloud Posse Engineering Team Review Required

This pull request modifies files that require Cloud Posse's review. Please be patient, and a core maintainer will review your changes.

To expedite this process, reach out to us on Slack in the #pr-reviews channel.

[codecov[bot]]

Codecov Report

:x: Patch coverage is 83.44371% with 25 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 69.65%. Comparing base (06fe90b) to head (1267bd0). :warning: Report is 20 commits behind head on main.

Files with missing lines	Patch %	Lines
pkg/auth/providers/aws/saml.go	78.50%	14 Missing and 9 partials :warning:
pkg/logger/logrus_adapter.go	95.45%	2 Missing :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1747      +/-   ##
==========================================
+ Coverage   69.60%   69.65%   +0.04%     
==========================================
  Files         397      398       +1     
  Lines       36288    36416     +128     
==========================================
+ Hits        25260    25367     +107     
- Misses       8720     8734      +14     
- Partials     2308     2315       +7     

Flag	Coverage Δ
unittests	69.65% <83.44%> (+0.04%)	:arrow_up:

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
errors/errors.go	100.00% <ø> (ø)
pkg/logger/logrus_adapter.go	95.45% <95.45%> (ø)
pkg/auth/providers/aws/saml.go	77.27% <78.50%> (-0.72%)	:arrow_down:

... and 2 files with indirect coverage changes

:rocket: New features to boost your workflow:

• :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[mergify[bot]]

[!WARNING]

This PR exceeds the recommended limit of 1,000 lines.

Large PRs are difficult to review and may be rejected due to their size.

Please verify that this PR does not address multiple issues. Consider refactoring it into smaller, more focused PRs to facilitate a smoother review process.