---
name: google-workspace-oauth-remediation
description: Verify Google Workspace OAuth app permissions and scopes with gws, confirm apps are not effectively allow-all, review app access control and domain-wide delegation risk, and produce prioritized remediation outputs from Admin Reports evidence.
---

# Google Workspace OAuth Remediation

Use this skill when the task is to verify Google Workspace OAuth permissions, review third-party app scope grants, confirm whether an app is effectively `allow all`, or prioritize remediation work from Google Workspace Admin Reports.

## Default Rules

- Use read-only Admin Reports access only unless the user explicitly asks for broader Google admin changes.
- Treat the `token` and `admin` feeds as the primary evidence sources.
- Treat `access_evaluation` as contextual only; include it only when the user wants higher-volume correlation.
- Do not claim an app is not `allow all` until current Admin Console checks are completed.
- Search by exact OAuth client ID, not only app name.

## Workflow

1. Confirm `gws` is installed and the saved session has the required Admin Reports scopes.
   Run `scripts/check_gws_auth.sh`.
2. Export the minimum incident feeds.
   Run `scripts/run_oauth_incident_review.sh --start <iso> --end <iso> --output-dir <dir> [--tenant <domain>]`.
3. Review the generated outputs in this order:
   - `oauth_incident_report.md`
   - `oauth_focus_app_matrix.csv`
   - `oauth_remediation_report.md`
   - `manual_current_app_access_checklist.md`
   - `oauth_admin_control_changes_180d.json`
4. If you need broader application context, rerun with `--include-access-evaluation`.
5. Use the current-state checklist to confirm whether the app is `Trusted`, broad `Specific Google data`, `CAA exempt`, or present in Domain-Wide Delegation.

## Risk Rules

- `P1`: AI, developer, or automation apps with Gmail, Drive, Admin, Cloud, or similarly sensitive scopes; unknown high-adoption apps; or any app with trust-like admin history.
- `P2`: identity-only AI or developer apps, or non-focus apps with business-sensitive data scopes that need explicit approval.
- `P3`: hygiene cleanup, policy tightening, and documentation follow-up.

## Script Entry Points

- `scripts/check_gws_auth.sh`
- `scripts/export_admin_reports.sh --start <iso> --end <iso> --output-dir <dir> [--apps csv]`
- `scripts/run_oauth_incident_review.sh --start <iso> --end <iso> --output-dir <dir> [--tenant <domain>] [--include-access-evaluation]`
- `scripts/oauth_incident_review.py --input-dir <dir> --tenant <domain> --start <iso> --end <iso>`
- `scripts/scan_oauth_admin_controls.py --start <iso> --end <iso> --output <path> [--history-days 180]`
- `scripts/build_oauth_remediation_report.py --input-dir <dir> --tenant <domain> --start <iso> --end <iso>`

## Resources

- `references/required-scopes.md`
- `references/auth-troubleshooting.md`
- `references/app-access-states.md`
- `references/risk-ranking.md`
- `references/remediation-priorities.md`
- `references/export-layout.md`
- `references/command-recipes.md`