Aplikace Requestor (dále Helpdesk) podporuje mimo jiné také autentizační protokol OpenID Connect, který technicky rozšiřuje protokol OAuth 2.0 a umožňuje ověřování identity uživatelů pomocí třetí strany. Typicky se jedná o tzv. systémy IAM (Identity and Access Management), které si kladou za cíl poskytnout společnostem a organizacím jednotné přihlašování do všech aplikací pomocí jednoho centrálně spravovaného účtu.
Jedním z takových systému je KeyCloak, který poskytuje právě výše uvedenou centrální správu uživatelů a umožňuje využití autentizačního protokolu OpenID Connect pro aplikace.
V tomto návodu popisujeme postup, kterým lze nakonfigurovat Requestor pro ověření oproti účtům systému KeyCloak s využitím principu SSO (Single Sign-On) a jaké nastavení je potřeba provést na straně systému KeyCloak.
KeyCloak nenahrazuje účet v aplikaci Requestor
Aby přihlášení fungovalo, v aplikaci Requestor se musí již nacházet uživatelský účet, který bude identifikovatelný pomocí KeyCloak (jak bude vysvětleno později). Aplikace Requestor v současné verzi nové účty v rámci integrace OpenID Connect nevytváří, takže pokus o přihlášení přes KeyCloak, pokud daný účet v aplikaci Requestor neexistuje, skončí chybou.
S ohledem na tuto skutečnost není aktuálně důležité, jakým způsobem došlo k tvorbě uživatelského účtu. Může se jednat o interní účet Requestor, může jít o účet synchronizovaný z Active Directory, apod., důležité je, že jej bude možné jednoznačně identifikovat.
Konfigurace na straně KeyCloak
Systém KeyCloak by měl obsahovat alespoň jeden tzv. Realm, ve kde se nachází uživatelské účty, které chceme použít pro autentizaci. V daném Realmu následně vytvoříme nového klienta (Client), který bude obsahovat specifickou konfiguraci pro ověřování aplikace Requestor.
Po vybrání odpovídajícího Realmu (na obrázku níže jde o Realm rq-test) klikneme na záložku Clients a následně tlačítko Create client.
Otevře se nám nový formulář, který ve třech krocích nastaví základní údaje. V prvním kroku jako Client type vybereme OpenID Connect a zvolíme si jedinečné Client ID, které budeme potřebovat později během konfigurace aplikace Requestor. Následně klikneme na tlačítko Next.
Ve druhém kroku je potřeba povolit volbu Implicit flow. Volitelně lze také povolit Client authentication, což vygeneruje tzv. Client Secret, bez kterého nebude možné aplikaci pro ověření oproti systému KeyCloak použít. Ačkoli se jedná o nepovinnou součást, využití této možnosti důrazně doporučujeme a v tomto návodu si ukážeme nastavení s tímto dodatečným ověřením.
V poslední kroku dialogu vyplíme Valid redirect URIs a Web origins. Abychom nemuseli vyplňovat konkrétní adresy, dá se předpokládat, že je v pořádku povolit všechny potenciální adresy aplikace Requestor, proto lze použít tvar adresy např. https://zakaznik.servicedesk.net/*, kde díky hvězdičce povolíme všechny potenciální adresy z dané aplikace, a to jak pro příchozí spojení, tak pro přesměrování po přihlášeni, resp. odhlášení.
Celou konfiguraci uložíme kliknutím na tlačítko Save.
V tuto chvíli by mělo být na straně KeyCloaku vše potřebné nastavené. Zbýva poslední krok, kterým je zjištění a vykopírování potřebných odkazů a tajného klíče. Budeme potřebovat následující:
OpenID Authority URL
OpenID Logout URL
Client ID
Client Secret
První dva odkazy lze asi nejlépe vyčíst z .well-known/openid-configuration, což je dostupné jako odkaz OpenID Endpoint Configuration ze stránky Realm settings.
Kliknutím na OpenID Endpoint Configuration se nám zobrazí konfigurační soubor ve formátu JSON, ze kterého lze vyčíst dvě adresy, které budeme potřebovat. Příklad z naší testovací instance:
"issuer":"https://id.requestor.net/auth/realms/rq-test""end_session_endpoint":"https://id.requestor.net/auth/realms/rq-test/protocol/openid-connect/logout"
Vyhledáním řetězce issuer a end_session_endpoint můžeme najít odpovídající odkazy a ty si někam odložit. Na hlavní konfigurační stránce si můžeme navíc vidět Realm ID.
Poslední informací, která bude potřeba, je Client secret, který se nachází v konfiguraci klienta (sekce Clients). Po rozkliknutí odpovídajícího nastavení (vytvářeli jsme jej v předchozích krocích) překliknutím do záložky Credentials uvidíme řetězec Client Secret, který lze volitelně odkrýt a zkopírovat.
Nyní máme všechny potřebné informace a můžeme přistoupit ke konfiguraci na straně aplikace Requestor.
Konfigurace OpenID v aplikaci Requestor
V aplikaci Requestor přejdeme do Administrace, kde v sekci Zabezpečení klikneme na OpenID.
Na nově otevřené stránce vyplníme formulář, aby obsahoval potřebné informace, které jsme si v předchozích krocích zjistili:
Authority URL, v konfiguračním souboru ve formátu JSON se odkaz nacházel jako hodnota klíče
issuer,Logout URL,
Client ID,
Client Secret
Další konfigurovatelnou položkou je Identifikační údaj, který slouží k jednoznačné identifikaci uživatele. V naprosté většině nasazení se bude jednat o email, ale je možné zvolit i uživatelské jméno (pak musí být uživatelské jméno v aplikaci Requestor stejné, jako uživatelské jméno v nakonfigurovaném Realmu KeyCloaku.
U této volby doporučujeme ponechat email, přičemž je potřeba zajistit, aby nemělo více uživatelských účtů v aplikaci Requestor stejný email.
Text tlačítka nám umožňuje změnit výchozí popisek tlačítka na přihlašovací obrazovce. Po kliknutí na tlačítko budeme přesměrováni na ověření pomocí KeyCloaku, kde v případě úspěchu budeme navráceni zpět do aplikace Requestor a přihlášeni pod daným uživatelem.
Pod tímto polem najdeme volitelné nastavení Automaticky přesměrovat na přihlášení, které tuto úvodní přihlašovací obrazovku přeskočí a přesměruje nás rovnou na ověření KeyCloak. Pokud bychom přesto potřebovali přihlašovací dialog aplikace Requestor využít, v nastavení vidíme i adresu, kterou můžeme zadat do prohlížeče a k přesměrování na KeyCloak nedojde. Adresa vždy odpovída primární adrese vaší instance.
Během ověření na straně KeyCloak může dojít k chybě (nedostatečná práva, zakázaný účet, neexistující účet v aplikaci Requestor, apod.). V takové situaci standardně dojde k zobrazení chyby, kterou lze obejít vložením odkazu do pole Nepovinné URL při chybě ověření. Takto je možné uživatele nasměrovat například na nějakou informaci o tom, jak je možné přístup získat, nebo jak účet získat.
Po vyplnění všech potřebných údajů se ujistíme, že máme OpenID aktivované (zelený posuvník) a vše uložíme tlačítkem Uložit.
Po uložení je potřeba aplikaci restartovat (restart aplikačního poolu v IIS, případně restart celé website v IIS).
Při přihlášení pak můžeme kliknout na tlačítko OpenID (pokud jsme si nezvolili jiný text, resp. nezvolili automatické přesměrování při přihlášení) a měli bychom být ověřeni pomocí účtu v KeyCloaku (pokud již tam přihlášeni jsme, tak nás to rovnou ověří a vráti do aplikace Requestor, v opačném případě uvidíme přihlašovací obrazovku).
