Preskočiť na obsah
Beta verzia novej dokumentácie. Prejsť na starú verziu
Domov Konektory OAuth 2.0 konektor

OAuth 2.0 konektor

Naposledy aktualizované

Konektor OAuth 2.0 slúži na prihlasovanie externých aplikácií do CDESK bez zadávania hesla používateľa. Externá aplikácia (napríklad integračná služba, skript alebo nástroj umelej inteligencie) sa prihlási pod konkrétnym používateľom CDESK pomocou podpísaného prihlasovacieho tokenu. Token je podpísaný tajným podpisovacím kľúčom, ktorý je uložený v konektore a ktorý pozná aj externá aplikácia.

Po úspešnom overení tokenu CDESK vydá bežný prihlasovací token rozhrania API. Všetky ďalšie volania externej aplikácie potom prebiehajú pod identitou zvoleného používateľa a s jeho oprávneniami.

Princíp prihlásenia externej aplikácie cez konektor OAuth 2.0
Obrázok: Princíp prihlásenia externej aplikácie cez konektor OAuth 2.0

Čo konektor umožňuje – konektor sprístupňuje prihlásenie pre aplikácie, ktoré pristupujú do CDESK cez rozhranie API a nemajú k dispozícii heslo používateľa.

  • Prihlásenie podpísaným tokenom – externá aplikácia si sama vytvorí a podpíše prihlasovací token a odošle ho do CDESK, ktorý ho overí pomocou podpisovacieho kľúča z konektora.
  • Vydanie tokenu na základe identifikátora a kľúča – externá aplikácia, ktorá nevie token podpísať sama, môže od CDESK získať krátkodobý prihlasovací token zadaním identifikátora používateľa a podpisovacieho kľúča.
  • Prihlásenie pod konkrétnym používateľom – externá aplikácia pracuje s rovnakými oprávneniami ako používateľ, pod ktorým sa prihlásila, takže rozsah prístupu je možné riadiť bežnými oprávneniami CDESK.
Poznámka

Konektor nie je určený na prihlasovanie ľudí do webového rozhrania CDESK. Na prihlasovanie používateľov cez externého poskytovateľa identity slúžia iné konektory, napríklad Entra ID, ADFS alebo Google autentifikácia.

Predpoklady

Pred nastavením konektora je potrebné overiť tieto predpoklady:

  • Máte prístup do Globálnych nastavení s oprávnením na zápis.
  • V CDESK existuje aktívny používateľ, pod ktorým sa bude externá aplikácia prihlasovať, a poznáte jeho identifikátor (ID).
  • Externá aplikácia vie odoslať požiadavku na rozhranie API CDESK a uložiť si podpisovací kľúč.

V jednom prostredí CDESK je možné vytvoriť najviac jeden konektor OAuth 2.0. Po jeho vytvorení sa typ konektora v sprievodcovi pridaním konektora už neponúka.

Nastavenie konektora

Nastavenie konektora spočíva v zadaní alebo vygenerovaní podpisovacieho kľúča. Cieľom je, aby CDESK aj externá aplikácia poznali rovnaký tajný kľúč, ktorým sa podpisujú a overujú prihlasovacie tokeny. Formulár konektora nemá záložky ani tlačidlo na test pripojenia. Správnosť nastavenia sa preverí pri prvom prihlásení externej aplikácie.

Pridanie konektora

Konektor sa pridáva v sprievodcovi pridaním konektora týmto postupom:

  1. Otvorte Globálne nastavenia → Konektory, API. Zobrazí sa zoznam „Konektory do externých systémov“.
  2. Kliknite na tlačidlo Pridať konektor. Otvorí sa sprievodca „Pridanie konektora“.
  3. V poli Typ konektora vyberte možnosť OAuth 2.0 a kliknite na tlačidlo Pokračovať.
  4. Vyplňte pole Názov a ponechajte zapnutý prepínač Zapnuté.
  5. Do poľa Podpisovací kľúč zadajte kľúč s dĺžkou aspoň 32 znakov alebo kliknite na tlačidlo s ikonou kocky, ktoré vygeneruje náhodný kľúč.
  6. Kliknite na tlačidlo Vytvoriť. Po uložení sa zobrazí hlásenie „Konektor uložený“.
  7. Podpisovací kľúč bezpečným spôsobom odovzdajte správcovi externej aplikácie.
Formulár konektora OAuth 2.0 s poľom Podpisovací kľúč
Obrázok: Formulár konektora OAuth 2.0 s poľom Podpisovací kľúč

Význam polí

Formulár konektora obsahuje spoločné polia, ktoré majú všetky konektory, a jedno pole špecifické pre OAuth 2.0:

  • Typ konektora – zobrazuje typ OAuth 2.0. Pole nie je možné po vytvorení konektora zmeniť.
  • Názov – pomenovanie konektora v zozname konektorov. Pole je povinné a na funkciu konektora nemá vplyv.
  • Zapnuté – prepínač určuje, či je konektor aktívny. Prihlásenie externých aplikácií funguje len vtedy, keď je konektor zapnutý. Po vypnutí CDESK odmietne všetky prihlasovacie tokeny podpísané kľúčom z konektora.
  • Podpisovací kľúč – tajný reťazec, ktorým CDESK overuje podpis prihlasovacieho tokenu. Kľúč musí mať aspoň 32 znakov, inak sa pod poľom zobrazí upozornenie „Z technických a bezpečnostných dôvodov, dĺžka kľúča nesmie byť menšia ako 32 znakov“. Tlačidlo s ikonou kocky (popis „Vytvoriť náhodný podpisovací kľúč“) vyplní pole náhodným 32-znakovým kľúčom. Zmena kľúča sa prejaví po uložení konektora a externá aplikácia musí odvtedy používať nový kľúč.
Dôležité

Kto pozná podpisovací kľúč, môže sa prihlásiť pod ktorýmkoľvek používateľom vášho prostredia CDESK, ktorého identifikátor pozná. Kľúč preto uchovávajte ako heslo a pri podozrení na jeho únik ho okamžite zmeňte.

Pod poľom Podpisovací kľúč sa zobrazuje informačný rámček s popisom, aké údaje musí obsahovať prihlasovací token. Podrobný popis je uvedený v časti Používanie konektora.

Tlačidlá formulára

Vo formulári konektora sú dostupné tieto tlačidlá:

  • Vytvoriť (pri uloženom konektore Uložiť) – uloží nastavenie konektora. Nový podpisovací kľúč začne platiť až po uložení.
  • Zmazať – odstráni konektor. Tlačidlo sa zobrazí len pri uloženom konektore. Po kliknutí na tlačidlo Zmazať a potvrdení otázky „Naozaj chcete vymazať tento záznam?“ prestane prihlasovanie externých aplikácií fungovať.
  • Späť – vráti sa do zoznamu konektorov bez uloženia zmien.

Používanie konektora

Konektor sa v používateľskom rozhraní CDESK ďalej neprejavuje. Používa ho externá aplikácia pri prihlasovaní cez rozhranie API. Táto časť je určená správcovi externej aplikácie a opisuje, aké údaje musí obsahovať prihlasovací token a ako prebieha prihlásenie.

Údaje prihlasovacieho tokenu

Prihlasovací token je token vo formáte JWT (JSON Web Token) podpísaný algoritmom HS256 pomocou podpisovacieho kľúča z konektora. Kľúč sa pri podpise používa v kódovaní URL-safe Base64, ako uvádza informačný rámček vo formulári konektora. Token musí obsahovať tieto údaje:

  • iss – vydavateľ tokenu, pre tento spôsob prihlásenia hodnota external-auth-cdesk.
  • sub – identifikátor (ID) používateľa CDESK, pod ktorým sa chce externá aplikácia prihlásiť.
  • aud – doména servera CDESK, na ktorý sa token odosiela, napríklad firma.cdesk.sk. Hodnota sa musí presne zhodovať s adresou servera.
  • iat – čas začiatku platnosti tokenu.
  • exp – čas ukončenia platnosti tokenu. Odporúča sa krátka platnosť, napríklad 5 minút.

CDESK pri overovaní toleruje rozdiel času medzi servermi do 60 sekúnd.

Postup prihlásenia externej aplikácie

Externá aplikácia sa prihlasuje v dvoch fázach. Najprv získa prihlasovací token, potom ho vymení za prihlasovací token rozhrania API. Prihlásenie prebieha týmto postupom:

  1. Externá aplikácia vytvorí a podpíše prihlasovací token s údajmi podľa predchádzajúcej časti. Ak aplikácia nevie token podpísať sama, môže ho získať odoslaním identifikátora používateľa (client_id) a podpisovacieho kľúča (client_secret) na adresu /api/auth/jwttoken. CDESK v tom prípade vráti token s platnosťou 5 minút.
  2. Externá aplikácia odošle prihlasovací token na adresu /api/auth/login v hlavičke Authorization v tvare Bearer a token.
  3. CDESK overí podpis, adresu servera, používateľa a platnosť tokenu. Ak je všetko v poriadku, vráti prihlasovací token rozhrania API.
  4. Externá aplikácia používa prihlasovací token rozhrania API pri ďalších volaniach. Volania prebiehajú s oprávneniami zvoleného používateľa.
Príklad z praxe

Pre integračnú službu je vhodné vytvoriť samostatného používateľa, napríklad „Integrácia ERP“, a priradiť mu len oprávnenia, ktoré integrácia potrebuje. Externá aplikácia sa potom prihlasuje pod týmto používateľom a v histórii záznamov sú jej zmeny jednoznačne odlíšené.

Popis rozhrania API pre pripojenie z iných systémov je dostupný cez odkaz, ktorý sa zobrazuje pri zozname „Konektory do externých systémov“.

Riešenie problémov

Ak sa externá aplikácia nedokáže prihlásiť, CDESK vráti v odpovedi rozhrania API anglické chybové hlásenie. Nasledujúca tabuľka uvádza najčastejšie hlásenia a odporúčaný postup.

HlásenieČo znamená a ako postupovať
„Invalid JWT signature.“Podpis tokenu nesedí s podpisovacím kľúčom v konektore. Skontrolujte, či externá aplikácia používa aktuálny kľúč a či ho pri podpise správne kóduje.
„Token expired.“ alebo „Token used before iat.“Token už neplatí alebo ešte nezačal platiť. Skontrolujte časy iat a exp v tokene a nastavenie času na serveri externej aplikácie.
„Target server domain is not set in JWT claims…“Údaj aud v tokene chýba alebo sa nezhoduje s doménou servera CDESK. Do údaja aud zadajte presnú doménu, na ktorú sa token odosiela.
„User with the provided ID was not found.“ alebo „User not found for given client_id.“Používateľ so zadaným identifikátorom neexistuje. Skontrolujte hodnotu sub alebo client_id.
„OAuth2.0 connector was not found.“ alebo „OAuth2.0 connector not found for this user.“V prostredí používateľa nie je zapnutý konektor OAuth 2.0. Skontrolujte, či konektor existuje a či je zapnutý prepínač Zapnuté.
„Invalid client_secret.“Podpisovací kľúč odoslaný na adresu /api/auth/jwttoken sa nezhoduje s kľúčom v konektore.
„Invalid signing algorithm is used, HS256 is expected.“Token je podpísaný iným algoritmom. Externá aplikácia musí použiť algoritmus HS256.
„Pre daný typ už nie je možné vytvoriť ďalší konektor“Konektor OAuth 2.0 už v prostredí existuje. Upravte existujúci konektor namiesto vytvárania nového.

Bola táto stránka užitočná?