Definice JWT - záložka Detail

Uživatelský kód umožňuje jednoznačně identifikovat konkrétní definici JWT pro použití v API. Kód má maximální délku 10 znaků a nahrazuje původní interní ID definice při komunikaci s API. Jeho hodnota musí být unikátní, pokud není prázdná

Použití

Endpoint /currentuser/logintoken nově používá parametr jwtsettingcode místo původního jwtsetting_id. Tento parametr obsahuje uživatelský kód definice.

Chování bez parametru jwtsettingcode

• Pokud neexistuje žádná definice typu Přihlášení do API, API vrací chybu: "Je potřeba založit alespoň jednu definici typu Přihlášení do API."
• Pokud existuje právě jedna definice typu Přihlášení do API, API ji použije a vrátí token.
• Pokud existuje více definic, API vrací chybu: "Není jednoznačně určena definice."

Chování s parametrem jwtsettingcode

• Pokud definice s daným kódem neexistuje, API vrací chybu: "Definice s uvedeným kódem neexistuje."
• Pokud definice existuje, API ji použije.

Oblast umožňuje specifikovat způsob přihlašování do API. K dispozici jsou tyto možnosti:

• Přihlášení do API
  • Tato oblast je určena pro generování tokenů, které následně slouží k autentizaci při přihlašování do API.
  • Tokeny vytvořené v této oblasti jsou interně spravovány a jejich použití je omezeno na vlastní systém API.
• Externí přihlášení do API
  • Tato oblast umožňuje autentizaci pomocí tokenů, které byly vygenerovány externí autoritou (např. jiným poskytovatelem identity).
  • Při použití této oblasti je uživatel identifikován pomocí e-mailové adresy uvedené v poli Položka s e-mailem.
  • Přihlášení selže, pokud je e-mail neunikátní mezi uživateli v systému.

Tato položka slouží k identifikaci přihlašovaného uživatele dle emailové adresy (viz Externí přihlášení do API). Výchozí hodnota je 'email'.

Pole Algoritmus definuje kryptografický algoritmus, kterým je podepsaný token. Toto pole je povinné a umožňuje zvolit jeden z podporovaných algoritmů:

• HMAC: Symetrický algoritmus využívající sdílený klíč.
• RSA: Asymetrický algoritmus s doporučením používat klíče o délce minimálně 2048 bitů.
• Ekliptické křivky (Elliptic Curves): Moderní asymetrický algoritmus s efektivnější správou klíčů.

Validace

Při ověřování tokenu validace zahrnuje:

• Ověření podpisu podle zvoleného algoritmu.
• Kontrolu shody následujících atributů tokenu s definicí:
  • Vydavatel (issuer)
  • Audience (příjemce)
  • Datum expirace
  • Povolení k přihlašování

Formát klíčů

Pro asymetrické šifry (RSA, ekliptické křivky) je nutné zadávat klíče ve formátu PEM. Příklad veřejného klíče:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6lsRee07cvY//50/+wWM46JuSRmXRjK4aaOSCZmAQpblnegfr69//EH/lctyeyj1sPouiYhNJpYltcfEIRwS90a54M7XPHyjlVKEE3MGJGY7oUlkwIP+uLuHJ+b602bGj7fVFhgJ/+4GJRIMzUtoOmcchNjjbEGyEfawYINu9yRZpjdMNZH1z7K/0NLvsfm3YQupVFMxg6oXmqRWkU/y8Z6k2s9dV62lQA5VvzhKVfRI55rd2X0BwITVctliaXHTHaioczzRLLowQMA/w+EOB7gZJeXeG8MirIn3rhnjkVqusCXV5SwI2tQPM2JxOMU0H/HK0bRlo97HZqWHqEU/hwIDAQAB
-----END PUBLIC KEY-----

Příklady generování klíčů

RSA

Privátní klíč 2048 bitů:

openssl genrsa -out rsa.private 2048

Veřejný klíč:

openssl rsa -in rsa.private -out rsa.public -pubout -outform PEM

Podporované algoritmy RSA: RS256, RS384, RS512

Ekliptické křivky

ES256:

openssl ecparam -genkey -name prime256v1 -noout -out ec256.private.pem
openssl ec -in ec256.private.pem -pubout -out ec256.public.pem

ES384:

openssl ecparam -genkey -name secp384r1 -noout -out ec384.private.pem
openssl ec -in ec384.private.pem -pubout -out ec384.public.pem

ES512:

openssl ecparam -genkey -name secp384r1 -noout -out ec512.private.pem
openssl ec -in ec512.private.pem -pubout -out ec512.public.pem

Položka Audience je součástí JWT specifikace a slouží k identifikaci zamýšlených příjemců, pro které byl token vystaven. Audience definuje účel tokenu a umožňuje kontrolu, zda token zpracovává oprávněný příjemce.

V systému ABRA Gen je pole Audience implementováno s ohledem na flexibilitu definovanou v RFC 7519 (JSON Web Token). To znamená, že hodnota Audience může být nepovinná, a pokud není vyplněna, systém při validaci JWT tokenu tuto hodnotu neověřuje. Tato funkčnost umožňuje použití externích JWT tokenů, které nemusí obsahovat pole Audience.

Význam pole Audience

Hodnota Audience identifikuje účel, pro který byl JWT token vystaven. Například při přihlašování do API může mít pole Audience hodnotu api. Pokud je definováno více konfigurací v agendě Nastavení JWT, je vhodné pomocí pole Audience rozlišit jejich účel. Hodnota Audience může být libovolný text odpovídající formátu StringOrURI, a její vyplnění není povinné.

Použití pole Audience

Vyplněné pole Audience

Pokud pole Audience obsahuje hodnotu, systém při validaci JWT tokenu kontroluje, zda hodnota Audience v tokenu odpovídá hodnotě zadané v konfiguraci Nastavení JWT. Při použití externího JWT tokenu je nutné zajistit, že hodnota Audience v tokenu odpovídá hodnotě zadané v tomto poli, jinak validace tokenu selže.

Prázdné pole Audience

Pokud je pole Audience nevyplněné, systém validaci tohoto claimu při kontrole JWT tokenu vynechává. Tato konfigurace umožňuje podporu tokenů, které pole Audience neobsahují, například při použití externích tokenů bez této informace.

Klíč, pomocí kterého se algoritmem H256 podepisují JSON Web tokeny. Podepsaný token je možné ověřit pouze pomocí stejného tajného klíče. Pokud někdo změní jakoukoli část tokenu (hlavičku nebo tělo), podpis již nebude platný, pokud se znovu nevytvoří pomocí stejného tajného klíče.

Veřejný klíč v JSON Web Token (JWT) je součástí asymetrického šifrování, které se používá k ověření podpisu tokenu. JWT může být podepsán pomocí soukromého klíče a ověřen pomocí odpovídajícího veřejného klíče. Tento proces zajišťuje, že token nebyl změněn a že pochází z důvěryhodného zdroje.

Doba v minutách, po kterou je možné použít čerstvě vygenerovaný JSON Web token k přihlášení. Výchozí hodnota je 60 minut.

Pokud je parametr povolen, pak se kromě přístupového JSON Web tokenu vygeneruje i tzv. obnovovací JSON Web token, který je možné použít k opětovnému vystavení nového přístupového i obnovovacího JSON Web tokenu.

Doba v minutách, po kterou je možné použít obnovovací JSON Web token. Výchozí hodnota je jeden týden. Viz také položka Platnost od obnovovacího JWT Tokenu.

Do tohoto pole se zadává URL, která vrací seznam veřejných klíčů k danému účtu ve formátu JWKS (JSON Web Key Set). Pokud je toto pole vyplněné, není povinné vyplňovat pole Veřejný klíč.

Funkce umožní vygenerovat náhodný Tajný klíč, který slouží k podepisování JSON Web Tokenů.