Token Broker — automatické prihlásenie

Token Broker je model pre doplnky, ktoré bežia priamo vnútri KROS platformy: používateľ klikne raz v obchode doplnkov a je automaticky prihlásený vo vašom doplnku, jeho firmy sa prepoja a doplnok dostane access token na KROS OpenAPI. Ide o server-to-server protokol s podpísaným JWT, jednorazovým launch code a zdieľaným API kľúčom — nie o samoobslužný model, ktorý by ste si mohli nasadiť sami.

Čo to rieši

V obchode doplnkov v KROS aplikácii klikne používateľ na jedno tlačidlo a tromi vecami naraz: je automaticky prihlásený vo vašom doplnku bez zadávania hesla, jeho firma (alebo firmy) v KROSe sa prepoja s doplnkom, a doplnok dostane access token na KROS OpenAPI, ktorým môže volať KROS v mene tejto firmy.

Prehliadač používateľa nikdy nevidí tento access token na KROS OpenAPI — prenáša sa výhradne server-to-server, medzi KROS Gatewayom a vaším doplnkom. Prehliadač nesie iba jednorazový, krátko platný code, ktorým sa na konci toku vytvorí prihlásená relácia.

Roly a hranice

KROS vlastní celý front-end tok a podpisovanie tokenov. Vy implementujete iba stranu doplnku — tri HTTP endpointy.

Celý tok

Kompletná sekvencia od kliknutia až po prihlásenú reláciu vo vašom doplnku:

Endpointy, ktoré implementujete

Tieto tri cesty sú fixné konštanty protokolu, nie sú konfigurovateľné. KROS ich skladá ako {BaseUrl}/api/auth/token-exchange, {BaseUrl}/api/auth/token-delivery a {BaseUrl}/auth/callback, kde BaseUrl je HTTPS adresa vášho doplnku dohodnutá s KROSom.

POST /api/auth/token-exchange

X-Plugin-Api-Key: VLOZ_SEM_API_KEY
Content-Type: application/json

{ "token": "<RS256 JWT>" }

Identita používateľa a firmy nie sú samostatné polia tela požiadavky — sú to claimy v samotnom JWT (nižšie).

1. Overte X-Plugin-Api-Key porovnaním s konštantným časom — inak 401.
2. Overte JWT: podpis cez JWKS, iss, aud, exp, algoritmus obmedzený len na RS256, plugin_id zodpovedá vášmu — inak 401.
3. Prečítajte sub a tenant_ids.
4. Vygenerujte jednorazový launch code (64 znakov, TTL 30 s) a uložte ho spolu s (userId, tenantIds, pluginId).
5. Rozhodnite, či potrebujete access token (requestAccessToken) — typicky true, ak ho pre danú firmu ešte nemáte.

{ "launchCode": "<64-znakový kód>", "requestAccessToken": true }

400 = chýba token. 401 = zlý API kľúč alebo neplatný podpis JWT.

JWT claimy

POST /api/auth/token-delivery

Zavolá sa iba ak ste v odpovedi na token-exchange vrátili requestAccessToken: true.

X-Plugin-Api-Key: VLOZ_SEM_API_KEY
Content-Type: application/json

{
  "userId": "user@example.com",
  "tokens": [
    { "tenantId": "123456", "name": "Moja Firma s.r.o.", "accessToken": "<opaque-token>" },
    { "tenantId": "789012", "name": "Druhá Firma a.s.", "accessToken": "<opaque-token>" }
  ],
  "pluginId": "fiskalpro"
}

1. Overte X-Plugin-Api-Key.
2. Overte, že pluginId zodpovedá vášmu — inak 400.
3. Prázdne pole tokens → vráťte 200 ako no-op.
4. Pre každý záznam bezpečne uložte accessToken pod kľúčom (userId, tenantId, pluginId); záznamy s prázdnym tenantId alebo accessToken preskočte.
5. Vráťte 200.

GET /auth/callback?code=…

Sem KROS na konci launchu presmeruje prehliadač používateľa.

1. Overte a atomicky skonzumujte code — je single-use, to je jeho jediná ochrana proti replay útoku. Neplatný, expirovaný alebo už použitý kód → 400.
2. Z uloženého záznamu (userId, tenantIds, pluginId) vytvorte reláciu (napr. prihlásením s cookie).
3. Presmerujte na hlavnú obrazovku doplnku (302).

Bezpečnosť

• Konštantný čas pri porovnaní API kľúča. Bežné porovnanie reťazcov (==) sa spravidla zastaví na prvom nezhodnom znaku, čím cez čas odpovede prezradí kľúč po jednotlivých bajtoch. Použite funkciu na porovnanie s konštantným časom vo vašom jazyku (napr. CryptographicOperations.FixedTimeEquals v .NET, crypto.timingSafeEqual v Node.js, hmac.compare_digest v Pythone).
• RS256-only validácia JWT cez JWKS, s rotáciou kľúča podľa kid — presne preto existuje JWKS endpoint namiesto natvrdo zadaného verejného kľúča.
• Launch code: kryptograficky náhodný, 64 znakov, single-use, TTL 30 s. Pri distribuovanom nasadení (viac inštancií doplnku) použite úložisko s atomickým „získaj a zmaž" (napr. Redis), aby dve inštancie nemohli ten istý kód skonzumovať dvakrát súčasne.
• HTTPS všade — v produkcii povinné, HTTP iba lokálne pri vývoji.
• Rate limiting na oboch auth endpointoch — presné limity pre tento povrch nemáme potvrdené, pozri poznámku v Chyby a limity.
• Žiadne tajomstvá do logov — access tokeny, telá JWT ani API kľúč sa nelogujú. Chybové hlášky smerom von držte generické, detaily len na strane servera.

Čo dodá KROS a čo dodáte vy

KROS vám dodá:

Vy dodáte KROS:

Chybové stavy

Ak provider vráti pre všetky firmy prázdne tokeny, token-delivery sa preskočí a launch napriek tomu pokračuje — používateľ sa prihlási bez aktívneho pripojenia na KROS OpenAPI. Váš doplnok musí tento stav zvládnuť gracefully, nie ho vyhodnotiť ako chybu launchu.

Implementačný checklist

• Dohodnuté s KROSom: pluginId, BaseUrl, API kľúč, JWKS URL, prostredia, spôsob volania KROS OpenAPI.
• POST /api/auth/token-exchange: overuje X-Plugin-Api-Key; overuje JWT cez JWKS (RS256, iss=plugin-broker, aud=plugin, exp, plugin_id).
• Čítanie sub a tenant_ids (JSON pole); idempotentné „nájdi alebo vytvor" pre používateľa a firmy.
• Generovanie single-use launch code (64 znakov, TTL 30 s), vrátenie { launchCode, requestAccessToken }.
• POST /api/auth/token-delivery: overuje API kľúč a pluginId; bezpečne ukladá accessToken per firma.
• GET /auth/callback?code=…: atomicky skonzumuje code, vytvorí cookie reláciu, presmeruje.
• Volanie KROS OpenAPI uloženým access tokenom (per firma).
• HTTPS všade; tajomstvá sa nelogujú; rate limiting na auth endpointoch.
• Graceful spracovanie: 0 firiem, prázdny token pre firmu, 429, opakovaný launch s inou firmou (nová cookie relácia nahradí starú).

Dve varianty gateway

Protokol, ktorý doplnok implementuje, je identický bez ohľadu na to, ktorá KROS gateway launch spúšťa — líšia sa len tým, akú hodnotu nesie claim sub, a tým, ako presne používateľ launch spustil:

• Jedna varianta je produkčné zapojenie do KROS Fakturácie: sub nesie e-mail používateľa, tenanti sú firmy s príslušnou licenciou a access token zodpovedá licenčnému oprávneniu na KROS OpenAPI danej firmy.
• Druhá varianta je samostatná (štandalón) brána s vlastným prihlásením: sub nesie numerické ID z tohto prihlásenia.

Váš doplnok sa nemusí starať, ktorá z nich launch spustila — vidí vždy len token-exchange, token-delivery, callback a JWKS endpoint, so zhodným tvarom požiadaviek a odpovedí.

Nie ste v .NET?

Protokol je zámerne jazykovo nezávislý — je postavený na JSON, JWT a JWKS, teda na formátoch a štandardoch, ktoré má knižnicu takmer každý ekosystém. Ak váš doplnok nie je v .NET, nepotrebujete žiadnu konkrétnu knižnicu ani balík — implementujte priamo tri kontrakty popísané vyššie (token-exchange, token-delivery, callback) pomocou bežnej JWT knižnice vo vašom jazyku, ktorá vie overiť RS256 podpis cez JWKS.