How Frost works

Credential refresh

A refresh is the one job Frost does. It gets a fresh SSO token, turns it into profiles, and scans for EKS clusters — in that order, every time.

When Frost refreshes

A refresh starts in one of five ways:

• On a schedule. When a token is stored, Frost sets a timer for the moment that token expires — around eight hours out for a typical Identity Center configuration — and refreshes then.
• At launch. Starting Frost with no valid token in hand kicks off a refresh straight away.
• When you save the Login settings. Saving a start URL and region drops the current token and refreshes with the new ones.
• By hand. Refresh now in the tray menu, or Refresh Now on the Credentials page.
• By hotkey. The global refresh hotkey — ⌘⇧R on macOS, Ctrl+Shift+R elsewhere, and rebindable in behavior settings.

Only one refresh runs at a time. If one is already in flight the new trigger is ignored rather than queued, which is what keeps two runs from writing over each other's record in the Activity log.

What a run does

Every run is the same three steps, in the same order, and each one is recorded on the Activity page as it happens.

1. Token Frost registers (or reuses) its OAuth client, starts an AWS device authorization request, opens the sign-in page, and polls until AWS hands back an access token. That token, and its expiry, go into Frost's own configuration file and into ~/.aws/sso/cache/, where the AWS CLI looks for it. More about signing in →
2. Profiles With the token, Frost calls sso:ListAccounts and, for each account, sso:ListAccountRoles. Each account/permission set pair becomes a profile, and those profiles are merged into ~/.aws/config. Profile names → · The config file →
3. EKS Frost lists every AWS region, then tries eks:ListClusters in each region with each profile. Clusters it can describe are written to ~/.kube/config. EKS discovery →

Steps run in that order because each depends on the one before it: the profiles need the token, and the EKS scan assumes credentials for the profiles it is scanning with.

How the token is obtained

Frost uses the OAuth 2.0 device authorization grant — the same flow the AWS CLI uses for aws sso login:

• Register a client. On first use Frost registers a public OIDC client named Frost-<uuid> with AWS and stores the client id and secret. It is reused across refreshes and re-registered when it expires, or if AWS rejects it with InvalidClientException.
• Start a device authorization. AWS returns a device code, a verification URL, a lifetime and a polling interval.
• Open the sign-in page — in Frost's own window or in your default browser, per your Login Page setting.
• Poll for the token at the interval AWS asked for, until you approve, the device code expires, or you close the login window.

The access token that comes back is good for every account and permission set you can reach, for its lifetime. Frost stores it, schedules the next refresh for its expiry, and moves on to the profiles step.

Auto-open or notify first

Frost's Authentication Mode decides whether a scheduled refresh may put a login page on your screen:

• Auto-open browser (default) — the login page opens as soon as the token needs replacing. With federated SSO it usually completes without asking you anything.
• Notification + hotkey — Frost posts a system notification and waits. Click the notification or press the refresh hotkey when you are ready, and the login page opens then. The notification is only raised while you are at the machine, so one that comes due overnight arrives when you sit down — pointing at a device code issued then, rather than one that expired hours earlier. If you let it expire anyway, Frost offers it again later.

See behavior settings for the trade-off between the two.

When a run fails

What happens next depends on why it failed, because the two kinds of failure want opposite treatment:

• Nobody finished the sign-in — the notification went unanswered, the device code expired unapproved, the page wanted a password with nobody there to type it. Frost replaces it, immediately and with no backoff: AWS keeps a device code alive for about ten minutes, and when one dies the next sign-in starts at once. That is the point of the whole app — credentials that are current whether or not anyone is at the machine — so there is deliberately no "waiting for you" gap in it. Only you ending the sign-in yourself — closing the login window, refusing it at your identity provider — stops that, because that is you saying "not now"; the next refresh is then the one you start.
• Nobody was there at all — then nothing is ever put on your screen. When the page turns out to need a person, Frost holds that sign-in instead of showing it: no window, no browser tab, no notification. The page keeps being driven in the background, so a slow identity provider or a dropped network still comes through on its own; and the moment you touch the keyboard, the login page Frost has been holding appears — already loaded, within a few seconds. You come back to a live sign-in rather than the wreck of one that expired at 3am.
• Something else failed — no network, an AWS error before any login page opened. Nothing is on your screen to pile up, so Frost retries on its own: a minute later, then two, doubling up to half-hourly until one succeeds.
• If the token was renewed and a later step failed — profiles, EKS — the credentials are good, so Frost stays on the normal schedule and tries the whole run again when they expire.
• The error is stored and shown on the Credentials page, with the failing step marked on the Activity page.
• Errors are recorded with the AWS exception name, HTTP status and request id where AWS provides them, which is what makes them worth pasting into a bug report.

Common failures and their fixes are collected in troubleshooting.

AWS permissions used

The first three are unauthenticated OIDC endpoints; the rest run with the token or the profile credentials that come from it. Failures in the EKS step are expected and harmless — most profiles have no EKS access, and those regions are simply skipped.