Keep your apps working through a sign-in outage
Cache Scrydon's discovery document and signing keys the way Scrydon tells you to, so your apps keep accepting the tokens they already hold when sign-in is briefly unavailable.
Your app does two different things with Scrydon:
- It sends people to sign in, and exchanges the code for tokens. That needs Scrydon to answer, every time.
- It checks the tokens it already holds, on every request. That needs only Scrydon's discovery document and its signing keys (the JWKS), and both can be cached.
If your app caches them as described here, a person who is already signed in keeps working while Scrydon's sign-in is unavailable. Only new sign-ins and token refreshes wait for it to come back.
What Scrydon tells your cache
Scrydon sends a Cache-Control header on every successful answer:
| Document | URL | Cache-Control |
|---|---|---|
| OIDC discovery | <issuer>/.well-known/openid-configuration | public, max-age=3600, stale-if-error=86400 |
| Authorization server metadata | <issuer>/.well-known/oauth-authorization-server | public, max-age=3600, stale-if-error=86400 |
| Signing keys | <issuer>/jwks (the jwks_uri in discovery) | public, max-age=600, stale-if-error=86400 |
<issuer> is https://<auth host>/api/auth, or your
organization's issuer
https://<auth host>/api/auth/o/<organization id>. Both send the same headers.
max-ageis how long a copy is fresh: one hour for discovery, ten minutes for keys.stale-if-error=86400lets your cache keep using an expired copy for up to one day when Scrydon answers with an error or does not answer at all.
An error answer never carries these headers, so your cache never stores one.
What to configure in your app
- Cache discovery and the JWKS rather than fetching them per request. Most
OIDC and JWT libraries do this already; check that yours respects the
server's
Cache-Controlor set the same times by hand. - Keep the last good copy when a refresh fails. If your library has no
stale-if-errorsupport, keep the previous JWKS in memory and use it until a refresh succeeds, for up to a day. - Refetch the JWKS once when a token names a key you do not have (an
unknown
kid). Scrydon starts signing with a new key without announcing it in advance, which is why the keys'max-ageis only ten minutes. Refetch at most once per unknownkid, not on every request. - Do not cache a token endpoint, authorize or userinfo answer. They are per-person and per-request.
What stays down during an outage
| Checking a token your app already holds | Keeps working, with the cached keys |
| A person signing in to your app | Waits for Scrydon |
| Refreshing a token | Waits for Scrydon. Let the person keep working until the access token expires, and retry the refresh with backoff. |
| Calling userinfo | Waits for Scrydon. If your app only needs the claims at sign-in, read them from the ID token instead. |
Rate limits
| Endpoint | Limit |
|---|---|
Token (/oauth2/token) | 600 successful requests per minute per app (client ID), from any address. Failed requests are limited to 20 per minute per IP address. |
| JWKS and discovery | 1,000 requests per 10 seconds per IP address |
| Sign-in and authorize | Per IP address, sized against password guessing |
Limits are counted on each Scrydon replica. A refused request gets
429 Too Many Requests with a Retry-After header in seconds; the token
endpoint's body is {"error": "temporarily_unavailable"}. Wait that long, then
retry.
A cached JWKS stays far below its limit. An app or proxy that fetches the JWKS or discovery on every request can still be refused. Caching as above avoids that.