improve SAML authorization workflow

[litlfred]

SAML Authorization Workflow Enhancement Requirements

Context

This document outlines requirements for enhancing the SAML SSO authorization workflow in @litlfred/sgex, with the implementation to be aligned with ongoing cross-tab communication work in PR #1120.

---

Goals

• Seamless SAML authorization: Detect, prompt, and resolve SAML SSO requirements with minimal user friction.
• Robust state: Handle multi-tab scenarios, reloads, and session transitions gracefully.
• Full activity logging: Capture all relevant events for troubleshooting and analytics.
• NEW: Clearly surface SAML authorization status and controls in the user dropdown menu.

---

Functional Requirements

1. Modal Trigger & State Management

• Modal trigger: On SAML SSO enforcement error (HTTP 403), show a SAML modal with actionable instructions.
• State persistence: Track pending SAML requests per organization/repository in sessionStorage.
• Single modal per org: Use cross-tab communication (via PR Investigation and Implementation: PAT token disappearance fix with stable fingerprint and cross-tab sync #1120 mechanisms, e.g., BroadcastChannel) to ensure only one modal per org is visible across all tabs.
• Multi-org support: Allow multiple concurrent SAML requests for different orgs, with modals managed per org.

2. Modal UI

• Instructions: Clearly describe why authorization is needed, steps to authorize, expected outcomes, and cooldown/"Later" behavior.
• Actions:
  • Authorize: Opens the GitHub SSO page in a new tab/window. Keep a reference to this window.
  • Later: Dismisses modal, starts a cooldown (default 1 minute) for the org.
• Accessibility: Modal must have ARIA attributes and be keyboard accessible.
• Branding: Use SGEX/WHO styling and dark mode support.

3. Polling for SAML Status

• Start: When "Authorize" is clicked, start polling every 3 seconds.
• Status check: Poll by retrying the original failed API call (or a minimal SAML-protected call).
• Stop: Polling ends when:
  • SAML authorization is detected (API call succeeds)
  • User closes modal or navigates away
  • Polling timeout is reached (default: 5 minutes)
• Cross-tab sync: Polling state must be synchronized so only one tab polls per org at a time.

4. Automatic Retry

• Retry: On successful SAML authorization, automatically retry the original request.
• UI update: If retry succeeds, close modal and update UI. If it fails for a non-SAML reason, show error.
• User feedback: Log and display outcome to user.

5. Session Storage

• Pending state: Store pending SAML requests and polling/cooldown state in sessionStorage (or localStorage if needed for cross-tab).
• Cleanup: On authorization, remove org from pending/cooldown lists.
• Reload recovery: On tab reload, check session state to resume polling or modal display if needed.

6. Cross-Tab Communication

• Modal visibility: Use cross-tab communication to ensure only one modal per org is open.
• Polling: Coordinate so only one tab polls per org.
• State sync: On SAML completion, broadcast to all tabs to close modal, stop polling, and cleanup state.

7. Logging

• Event logging: Log all major events:
  • Modal open/close, "Authorize"/"Later" actions
  • Polling starts/stops, ticks, timeouts
  • SAML authorization detected
  • Automatic retry attempts and outcomes
  • Cross-tab sync events
  • Session/cooldown changes
  • NEW: SAML status checks and UI actions from user dropdown
• Log format: Structured logs with type, org, repo, user, timestamp, details.
• Levels: Support info, warn, error, debug.
• Debug view: Allow devs to view logs in UI or via dev tools.

8. Edge Case Handling

• SSO tab closure: If SSO tab closes before authorization, keep polling and show reminder.
• Rate limiting: If polling causes rate limiting, back off and notify user.
• Token change: Reset SAML workflow and session state if the user changes their PAT.
• Multiple orgs: Handle multiple simultaneous org requests, one modal per org.

9. Extensibility

• Configurable intervals: Polling interval and timeouts should be configurable.
• Customizable modal: Modal text/branding per org.

---

NEW: User Dropdown SAML Status and Controls

10. SAML Status in User Dropdown

• Display: Under the user-dropdown div, show SAML authorization status for all relevant organizations.
  • For each org, show "Authorized" or "Not Authorized."
  • Show status for all orgs relevant to the current user/session.
• Dynamic Refresh: When the dropdown is visible, refresh SAML status every 10 seconds.
  • Polling should stop when dropdown closes.
  • Status should update in real-time if changes are detected.
• Initiate Authorization: For any org not authorized, provide a button or link to initiate SAML authorization for that org, via the modal workflow.
• Logging: All dropdown SAML status checks, refreshes, and authorization actions should be logged.
• Accessibility: Dropdown controls/buttons must be accessible and support keyboard navigation.

---

Non-Functional Requirements

• Performance: Polling, logging, and cross-tab sync must not impact app responsiveness.
• Security: No sensitive data in logs or broadcast messages.
• Reliability: Must recover gracefully from errors, tab closes, reloads, or sync failures.
• Testability: Modular code and automated tests for polling, modal, session, cross-tab, logging, and dropdown UI.

---

Future Enhancements

• UI indicator: Show SAML authorization status for orgs/tokens in main UI and user dropdown.
• Batch authorization: If supported by GitHub, allow batch SAML auth.
• Custom redirect: If GitHub allows, return user directly to SGEX after SSO.

---

Acceptance Criteria

• Modal appears on SAML enforcement error, single per org across tabs.
• Polling starts on "Authorize", stops on success, timeout, or user action.
• Automatic retry of original request and UI update on SAML completion.
• Session/cooldown state persists and syncs across tabs/reloads.
• All key events logged with structured data.
• UI meets accessibility and branding needs.
• Edge cases are handled as described.
• SAML status is shown in user dropdown, refreshes every 10s when visible, and allows user-initiated authorization.
• Code is modular and tested.

---

References

• SAML_WORKFLOW.md
• src/services/samlAuthService.js
• src/components/SAMLAuthModal.js
• Cross-tab communication PR #1120

[litlfred]

Goals
Seamless SAML authorization: Detect, prompt, and resolve SAML SSO requirements with minimal user friction.
Robust state: Handle multi-tab scenarios, reloads, and session transitions gracefully.
Full activity logging: Capture all relevant events for troubleshooting and analytics.
NEW: Clearly surface SAML authorization status and controls in the user dropdown menu.
Functional Requirements

1. Modal Trigger & State Management
   Modal trigger: On SAML SSO enforcement error (HTTP 403), show a SAML modal with actionable instructions.
   State persistence: Track pending SAML requests per organization/repository in sessionStorage.
   Single modal per org: Use cross-tab communication (via PR Investigation and Implementation: PAT token disappearance fix with stable fingerprint and cross-tab sync #1120 mechanisms, e.g., BroadcastChannel) to ensure only one modal per org is visible across all tabs.
   Multi-org support: Allow multiple concurrent SAML requests for different orgs, with modals managed per org.
2. Modal UI
   Instructions: Clearly describe why authorization is needed, steps to authorize, expected outcomes, and cooldown/"Later" behavior.
   Actions:
   Authorize: Opens the GitHub SSO page in a new tab/window. Keep a reference to this window.
   Later: Dismisses modal, starts a cooldown (default 1 minute) for the org.
   Accessibility: Modal must have ARIA attributes and be keyboard accessible.
   Branding: Use SGEX/WHO styling and dark mode support.
3. Polling for SAML Status
   Start: When "Authorize" is clicked, start polling every 3 seconds.
   Status check: Poll by retrying the original failed API call (or a minimal SAML-protected call).
   Stop: Polling ends when:
   SAML authorization is detected (API call succeeds)
   User closes modal or navigates away
   Polling timeout is reached (default: 5 minutes)
   Cross-tab sync: Polling state must be synchronized so only one tab polls per org at a time.
4. Automatic Retry
   Retry: On successful SAML authorization, automatically retry the original request.
   UI update: If retry succeeds, close modal and update UI. If it fails for a non-SAML reason, show error.
   User feedback: Log and display outcome to user.
5. Session Storage
   Pending state: Store pending SAML requests and polling/cooldown state in sessionStorage (or localStorage if needed for cross-tab).
   Cleanup: On authorization, remove org from pending/cooldown lists.
   Reload recovery: On tab reload, check session state to resume polling or modal display if needed.
6. Cross-Tab Communication
   Modal visibility: Use cross-tab communication to ensure only one modal per org is open.
   Polling: Coordinate so only one tab polls per org.
   State sync: On SAML completion, broadcast to all tabs to close modal, stop polling, and cleanup state.
7. Logging
   Event logging: Log all major events:
   Modal open/close, "Authorize"/"Later" actions
   Polling starts/stops, ticks, timeouts
   SAML authorization detected
   Automatic retry attempts and outcomes
   Cross-tab sync events
   Session/cooldown changes
   NEW: SAML status checks and UI actions from user dropdown
   Log format: Structured logs with type, org, repo, user, timestamp, details.
   Levels: Support info, warn, error, debug.
   Debug view: Allow devs to view logs in UI or via dev tools.
8. Edge Case Handling
   SSO tab closure: If SSO tab closes before authorization, keep polling and show reminder.
   Rate limiting: If polling causes rate limiting, back off and notify user.
   Token change: Reset SAML workflow and session state if the user changes their PAT.
   Multiple orgs: Handle multiple simultaneous org requests, one modal per org.
9. Extensibility
   Configurable intervals: Polling interval and timeouts should be configurable.
   Customizable modal: Modal text/branding per org.
   NEW: User Dropdown SAML Status and Controls
10. SAML Status in User Dropdown
    Display: Under the user-dropdown div, show SAML authorization status for all relevant organizations.
    For each org, show "Authorized" or "Not Authorized."
    Show status for all orgs relevant to the current user/session.
    Dynamic Refresh: When the dropdown is visible, refresh SAML status every 10 seconds.
    Polling should stop when dropdown closes.
    Status should update in real-time if changes are detected.