Discovery and keys
Every environment is its own OpenID Provider, with its own issuer, endpoints and signing keys. A standard OpenID Connect or OAuth 2 library needs only the issuer URL: everything else is in the discovery document.
The discovery document
Section titled “The discovery document”Both paths answer the same JSON (the second is the OAuth 2 name for it, RFC 8414), with Cache-Control: public, max-age=3600. No authentication is needed, and any origin may read it (Access-Control-Allow-Origin: *).
GET /.well-known/openid-configuration HTTP/1.1Host: your-app.auth.dev.seek.services{issuer} below is the environment’s issuer, such as https://your-app.auth.dev.seek.services: its host, over https.
| Field | Value |
|---|---|
issuer |
{issuer} |
authorization_endpoint |
{issuer}/authorize |
token_endpoint |
{issuer}/token |
userinfo_endpoint |
{issuer}/userinfo |
jwks_uri |
{issuer}/jwks.json |
revocation_endpoint |
{issuer}/revoke |
introspection_endpoint |
{issuer}/introspect |
end_session_endpoint |
{issuer}/logout |
authorization_challenge_endpoint |
{issuer}/authorize-challenge |
response_types_supported |
["code"] |
response_modes_supported |
["query"] |
grant_types_supported |
["authorization_code", "refresh_token", "client_credentials"]: client_credentials from machine clients only |
code_challenge_methods_supported |
["S256"] |
token_endpoint_auth_methods_supported |
["client_secret_basic", "none"] |
revocation_endpoint_auth_methods_supported |
["client_secret_basic", "none"] |
introspection_endpoint_auth_methods_supported |
["client_secret_basic"] |
dpop_signing_alg_values_supported |
["ES256"] |
authorization_response_iss_parameter_supported |
true |
subject_types_supported |
["public"] |
id_token_signing_alg_values_supported |
["ES256", "RS256"] |
scopes_supported |
["openid", "profile", "email", "phone", "offline_access"] |
claims_supported |
["iss", "sub", "aud", "exp", "iat", "auth_time", "nonce", "acr", "amr", "sid", "at_hash", "name", "picture", "email", "email_verified", "phone_number", "phone_number_verified"] |
acr_values_supported |
["aal1", "aal2"] |
prompt_values_supported |
["none", "login"] |
request_parameter_supported |
false |
request_uri_parameter_supported |
false |
claims_parameter_supported |
false |
refresh_grant_committed_within_ms |
8000: a refresh grant is committed within this many milliseconds of reaching the service, or not at all (a refresh that gets no answer). Not a standard field. |
The document names no pushed authorization requests (PAR), device authorization, front-channel or back-channel logout: none of them exists. Request objects (JAR) and the claims parameter are not supported either, as the three false fields say.
The key set
Section titled “The key set”The public keys every token of this environment is signed with, as a JSON Web Key Set, with Cache-Control: public, max-age=3600 and Access-Control-Allow-Origin: *. Each environment has keys of its own: a token from one environment never verifies against another’s keys.
{ "keys": [ { "kty": "EC", "crv": "P-256", "x": "…", "y": "…", "kid": "3f0c9a51e2b84d6f9a7c1e5b2d8f4a60", "use": "sig", "alg": "ES256" }, { "kty": "RSA", "n": "…", "e": "…", "kid": "9b1e7d3c0a4f4e2b8c6d5a1f0e9b7c32", "use": "sig", "alg": "RS256" } ]}| Key | Signs |
|---|---|
| ES256 (EC P-256) | Every access token, and ID tokens of clients that did not choose RS256. |
| RS256 (RSA 2048) | ID tokens of clients registered with id_token_alg: "RS256". |
A kid is 32 hexadecimal characters. Verify a token with the key its header’s kid names, and only with that key’s algorithm. There is never private material in the set.
Which keys are published
Section titled “Which keys are published”An environment has one active key of each algorithm. The set holds the public half of every key that is about to sign, signing now, or retired a short while ago:
- A new key is published 24 hours before it starts signing, so that caches have it before the first token it signs.
- A key is replaced after 90 days.
- A retired key stays in the set, and keeps verifying, for 24 hours after it stopped signing; then it is removed.
So the set holds one key per algorithm most of the time, and two around a rotation. An emergency rotation is the exception: it removes the retired keys at once, and tokens they signed stop verifying. See Keys and secrets.
Caching the keys
Section titled “Caching the keys”A verifier should cache the set and fetch it again when a token names a kid it does not know, rather than on every request; the one-hour max-age and the 24-hour overlap leave room for that. The Rust SDK keeps the set for an hour, refetches it for an unknown kid, at most once every 30 seconds, and keeps serving the keys it knows if a refetch fails.