# agent couldn't finish SSO login for a security audit: session expired mid-run

## TL;DR
Interactive SSO sessions are short by design, and a multi-hour audit outlives them. Do not run long audits on a browser SSO session. Switch the audit to a service account or machine credential with read-only audit scopes, checkpoint progress as you go, and re-authenticate non-interactively when the session lapses instead of starting over.

```text
agent couldn't finish SSO login for a security audit: session expired mid-run
```

## Use this when
- A long audit or scan dies partway with a session-expired error
- Re-authenticating means a human clicking through SSO again
- The audit restarts from zero after every expiry
- You need the audit to run unattended overnight

## Not for this skill when
- Login fails immediately (that is a credentials or IdP config problem, not expiry)
- The audit needs interactive access the service account cannot have
- You are setting up SSO for humans

## Steps
1. Confirm the failure is session expiry and not permissions: look for a 401 with a session or token-expired error rather than a 403.
   Expected: the error names an expired session, so you know re-auth (not new permissions) is the fix.
2. Create a service account or machine credential with the minimum read-only scopes the audit needs, approved through your normal access process.
   Expected: the credential authenticates to the audit APIs without a browser.
3. Break the audit into resumable chunks and write a checkpoint after each chunk: what is done, what is next.
   Expected: a checkpoint file that grows as the audit runs.
4. On expiry, re-authenticate with the machine credential and resume from the checkpoint.
   Expected: the audit continues where it left off instead of restarting.

### Variant: Okta session expired during long script
Use an Okta API token or OAuth service app with read scopes instead of the user session. API tokens have their own expiry; rotate them and keep them in the secret store.

### Variant: SSO re-authentication breaks automation run
Wrap the run loop so any session-expired error triggers re-auth and resume automatically. The run should treat expiry as routine, not fatal.

### Variant: SAML session timeout during security scan
Shorten the scan into chunks that fit inside the session lifetime, or ask the IdP admin to approve a session policy that fits the scan window.

## Why this happens
SSO sessions expire quickly on purpose to limit the damage of a stolen session. A human clicking through login again is a minor annoyance; an unattended multi-hour agent run treats the same expiry as a fatal error unless it was built to resume.

## Edge cases and pitfalls
- Some IdPs restrict audit APIs to human users; check before assuming the service account can reach everything.
- Refresh tokens expire too; plan for full re-auth, not just refresh.
- Checkpoints must not contain secrets or session tokens; store progress, not credentials.
- Get security-team approval for the service account and its scopes; an audit credential with broad write access is worse than the expiry problem.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NjgBJxIPYKr_R6VqZmaoJQ