RFC 7517 — JSON Web Key — Versola Docs
/docs
Pre-1.00.7.5versola.ioGitHub
RUEN

RFC 7517 — JSON Web Key

JWKS endpoint for public key distribution and JWT verification.

Specification: RFC 7517

JSON Web Key (JWK) defines a JSON format for cryptographic keys. Versola publishes a JWKS endpoint so that resource servers and relying parties can verify token signatures without calling the authorization server for each token.

Status

Partially implemented. Checked claims: 16 of 21.

JWKS endpoint

  • GET /.well-known/jwks.json endpoint (Section 5)
  • Content-Type: application/json response
  • Cache-Control: public, max-age=86400 — keys are publicly cacheable
  • Every active public key is in the set, so a rotation needs no downtime
  • No private key material is published (DiscoveryAndJwksSpec)

RSA key fields (Section 6.3)

  • kty — RSA
  • use — sig
  • alg — RS256 or PS256, as the operator published the key
  • kid — key identifier, matched against the JWT kid header
  • n and e — modulus and public exponent, Base64URL-encoded

EC key fields (Section 6.2)

  • kty — EC, with crv P-256, alg ES256, use sig, kid, x and y

Key types

  • RSA keys (kty: "RSA")
  • EC keys (kty: "EC", P-256 only)
  • EC keys on P-384 or P-521 — not supported
  • OKP keys (kty: "OKP", Ed25519) — not supported

Optional fields

  • x5c — X.509 certificate chain — not included
  • x5t — X.509 certificate SHA-1 thumbprint — not included
  • x5u — X.509 certificate URL — not included

Key rotation

  • Keys are generated in the admin console (Keys & metadata) as RS256, PS256 or ES256 and selected per tenant for signing (SigningKeySelectionSpec)
  • Verification picks the key by kid, so tokens signed with an older key stay valid while that key remains in the set
  • Clients register their own JWK Set for private_key_jwt, request objects and self_signed_tls_client_auth; see RFC 7523

Notes

  • A fapi2 tenant cannot select an RS256 key for signing, although the key can exist in the set; see FAPI 2.0.
  • A key published without a usable alg is skipped for signing and ignored by the advertised algorithm sets.

Where to look

The OpenAPI reference has the JWKS specification.