JWKS format: så är en nyckelfil uppbyggd

Ett jwks format är ett JSON-objekt med en enda huvudnyckel, keys, vars värde är en lista med nycklar. Varje nyckel beskrivs av ett JWK-objekt (JSON Web Key). Formatet definieras i RFC 7517, och fälten för de olika nyckeltyperna står i RFC 7518. Här visar vi hur filen är uppbyggd, vilka fält du behöver och vilka fel som brukar dyka upp när en jwks-fil skrivs för hand eller genereras av kod.

Så är ett jwks format uppbyggt

En jwks-fil har en toppnivå. RFC 7517 kräver att objektet har en medlem som heter keys, och att värdet är en array av JWK-objekt. En enskild JWK utan omslaget är alltså inte en jwks, även om den är giltig JSON.

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "kid": "Public key used in JWS spec Appendix A.3 example"
    }
  ]
}

Exemplet är nyckeln som RFC 7517 använder i sitt avsnitt 3. Det är en elliptisk kurvnyckel på kurvan P-256.

Fälten du behöver känna till

• kty anger nyckeltypen. EC och RSA är de vanligaste. RFC 7518 beskriver parametrarna för varje typ.
• crv, x och y beskriver en EC-nyckel. crv anger kurvan, och x och y är koordinaterna (RFC 7518, avsnitt 6.2.1).
• n och e beskriver en RSA-nyckel. n är modulen och e är exponenten (RFC 7518, avsnitt 6.3.1).
• kid är ett namn på nyckeln. Det används för att hitta rätt nyckel när listan har fler än en (RFC 7517, avsnitt 4.5).
• alg anger vilken algoritm nyckeln ska användas med, och use anger om nyckeln är till för signering eller kryptering (RFC 7517, avsnitt 4.2 och 4.4).

Ett fält du inte känner igen ska du inte ta bort. RFC 7517 säger att medlemmar som mottagaren inte förstår ska ignoreras. Samma medlemsnamn får däremot inte förekomma två gånger i en och samma JWK. Enligt RFC 7517 (avsnitt 4) ska parsers antingen avvisa nyckeln eller använda den sista förekomsten, och det är en vanlig källa till förvirring när filen byggs av flera verktyg.

Publika och privata fält

En jwks som publiceras ska bara innehålla publika nyckelparametrar. Fältet d finns i privata EC-nycklar (RFC 7518, avsnitt 6.2.2.1) och i privata RSA-nycklar (avsnitt 6.3.2.1). Det hör inte hemma i en publik lista. Ser du d, p, q eller andra privata parametrar i en fil som ska ut på nätet, ta bort dem och bygg filen på nytt från den publika delen av nyckeln.

Steg för att skriva ett jwks format

1. Välj nyckeltyp och algoritm tillsammans. ES256 är ECDSA med P-256 och SHA-256 (RFC 7518, avsnitt 3.1), så en ES256-nyckel ska ligga på P-256.
2. Ta fram den publika delen av nyckeln. För EC behåller du kty, crv, x och y. För RSA behåller du kty, n och e.
3. Lägg till ett kid som är unikt i listan.
4. Sätt alg och use där de behövs.
5. Lägg nyckeln i arrayen under keys och kontrollera att hela filen är giltig JSON.

Vanliga misstag

• En JWK i stället för en JWK Set. Ett objekt med kty men utan keys-omslag är inte en jwks.
• Dubbla medlemmar. Samma fält två gånger i en nyckel är ett fel enligt RFC 7517.
• Fel kurva för algoritmen. ES256 med en nyckel på annan kurva än P-256 stämmer inte med RFC 7518:s tabell över algoritmer.
• Privata fält kvar. Se avsnittet om publika och privata fält ovan.
• Flera nycklar utan kid. Då blir det svårt för den som läser filen att veta vilken nyckel som hör till vilken token.

Så kontrollerar du filen

Kontrollen tar några minuter. Klistra in filen i en JSON-validator och kontrollera att rotobjektet har keys. Gå sedan igenom varje nyckel: finns kty, och har nyckeln rätt parametrar för sin typ? Finns kid när listan har fler än en nyckel? Finns några privata fält kvar? Om det är tiden i en token som strular, och inte nyckelfilen, beskrivs det i JWT exp och nbf.

Vanliga frågor

Är jwks och JWK samma sak? Nej. En JWK är en nyckel. En JWK Set, ofta kallad jwks, är ett objekt som innehåller en lista med nycklar under keys (RFC 7517, avsnitt 5).

Kan en jwks innehålla både RSA- och EC-nycklar? Ja. Varje post i listan har sitt eget kty, så nyckeltyperna kan blandas i samma lista.

Måste varje nyckel ha ett kid? Det är inte en förutsättning för att filen ska vara giltig JSON, men det är en god vana när listan har fler än en nyckel, eftersom det gör det möjligt att välja rätt nyckel.

Kan jag använda ett jwks format för symmetriska nycklar? RFC 7518 har en parameter för symmetriska nycklar (k, avsnitt 6.4). En symmetrisk nyckel är hemlig, så den hör inte hemma i en publik jwks. Använd den bara i interna miljöer där båda sidor redan har nyckeln.