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. If you never do, the run gives up when the device code expires, and Frost waits for you rather than notifying again.

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 login window was closed, the notification was never answered, the device code expired unapproved, AWS reported the sign-in denied. Frost stops and waits for you. Trying again would only open another login page for nobody to complete, and an unattended machine would collect one every few minutes all night. The tray menu says Sign-in needed, a single notification tells you so unless you closed the window yourself, and the next refresh is the one you start.
• 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.