Zabezpečené operace, přihlašování

Veškeré webové služby jsou publikovány pouze prostřednictvím protokolu HTTPS, je tedy zajištěn bezpečný šifrovaný kanál mezi serverem a klientem. Ne každá webová služba však může být volána anonymně bez nutnosti přihlášení. Mnoho služeb přihlášení vyžaduje, aby vůbec mohly být zavolány. Některé služby přihlášení nutně nevyžadují, avšak pokud je volá uživatel s určitou rolí, vracejí například více informací a podobně.

Pro přenos přihlašovacích údajů se v každém případě (tj. u SOAP i REST služeb) používá standardní HTTP mechanismus HTTP BASIC.

Uživatelská konta a role v IS/STAG

Na začátek je třeba vysvětlit, jak IS/STAG pracuje s uživatelskými konty a rolemi uživatelů. Podstatné je to, že každá instalace IS/STAG (u různých zákazníků) může být nakonfigurována jinak a při vývoji klienta webových služeb IS/STAG je třeba být připraven na všechny možnosti.

Každý uživatel, jedna fyzická osoba, může mít v IS/STAG více rolí. Systém obsahuje mnoho různých rolí, například role student, vyučující, studijní referentka a další. Konkrétní seznam všech podporovaných rolí lze získat touto webovou službou. Každá role má specifická oprávnění v systému a specifické možnosti. Z toho důvodu je při každé operaci v systému třeba zcela jasně vědět, z titulu jaké role chce uživatel danou funkci provést. Je to vidět například v portálovém řešení, kde si uživatel musí nejprve vybrat svoji roli a na jejím základě jsou mu nabízeny další funkce.

Každá jednotlivá role přiřazena uživateli má svůj jedinečný identifikátor nazvaný "IS/STAG uživatelské jméno" (identifikátor je jedinečný napříč celým systémem a všemi uživateli), zcela jednoznačně identifikuje konkrétní roli konkrétního uživatele. U všech webových služeb, kterým na roli volajícího uživatele jakkoliv záleží, je přítomen parametr pojmenovaný stagUser. Při volání služby je třeba tento parametr vyplnit a uvést v něm ono "IS/STAG uživatelské jméno" identifikující roli, pod kterou je služba volána. (poznámka: jak bude vidět dále, hodnota tohoto parametru může být zcela odlišná od uživatelského jména, které klient použil pro přihlášení!).

Co se týče přihlašování do systému (tj. použití nějakého jména a hesla pro autentizaci), IS/STAG může být nakonfigurován dvěma způsoby, záleží na prostředí zákazníka:

Přihlašování ke každé roli zvlášť. V tomto případě je jako uživatelské jméno použito přímo "IS/STAG uživatelské jméno", heslo eviduje IS/STAG sám ve své databázi. Má-li uživatel více rolí v systému, musí se přihlašovat ke každé roli zvlášť a nemůže mezi nimi přepínat. Toto nastavení používají zákazníci, kteří nemají žádný větší systém na správu identit (například Kerberos, LDAP, Microsoft AD a podobně), typicky jsou to menší školy.
Přihlašování osoby přes externí systém. V tomto případě IS/STAG samotný neřeší hesla, ale umí delegovat přihlášení k nějakému externímu systému, který zákazník provozuje (například Kerberos, LDAP, Microsoft AD). V tomto případě však uživatelské jméno patří k celé osobě a nikoliv pouze k jednotlivé jedné její roli. Uživatel se přihlásí a následně může volat webové služby pod všemi svými rolemi tak, že pouze uvádí různé hodnoty parametru stagUser.

Technické podrobnosti

Při volání webové služby vyžadující přihlášení je možno předat přihlašovací údaje následujícími způsoby:

Základní způsob je předání uživatelského jména a hesla metodou HTTP Basic. V případě, že toto jméno a heslo klientská aplikace má k dispozici (což není častý případ a není doporučený), používá se spíše pro jednorázové připojování těch systémů, které mají k dispozici vlastní konto v systému IS/STAG.

Metodou HTTP Basic lze předat nejen kombinaci uživatelského jména a hesla, ale lze předat taktéž tzv. uživatelský ticket, což je serverem náhodně vygenerovaný řetězec, který reprezentuje přihlášení uživatele. Ticket se v HTTP Basic použije jako uživatelské jméno (heslo je třeba použít prázdný řetězec). Tento ticket lze získat těmito způsoby:

V případě úspěšného zavolání jakékoliv webové služby, která akceptovala přihlášení, vrací server ve své odpovědi speciální COOKIE s názvem WSCOOKIE, jejíž hodnotou je uživatelský ticket. Namísto HTTP Basic lze předat při volání tuto COOKIE serveru a tím dojde k přihlášení.

V případě, že externí aplikace chce nechat svého klienta (cílového uživatele) přihlásit k modulu WS a získat nazpět jeho ticket (který následně bude sama používat pro komunikaci s modulem WS), přesměruje svého uživatele na modul webových služeb na speciální adresu a jako parametr originalURL uvede URL, na které bude uživatel po úspěšném přihlášení přesměrován zpět. Je možno si vybrat ze dvou způsobů - buď aplikace zobrazí webový přihlašovací formulář a nebo rovnou vyžaduje HTTP Basic. Doporučujeme první způsob:

Formulářové ověření: https://stag-demo.zcu.cz/ws/login?originalURL=http://www.stag-client.cz
Formulářové ověření s použitím pouze hlavní metody přihlašování na dané škole: https://stag-demo.zcu.cz/ws/login?originalURL=http://www.stag-client.cz&onlyMainLoginMethod=1
HTTP BASIC Ověření [doporučujeme nepoužívat, bude odebráno]: https://stag-demo.zcu.cz/ws/login?originalURL=http://www.stag-client.cz&basic=1

Je-li v případě formulářového přihlášní použit parametr onlyMainLoginMethod=1, pak se na větších školách, kde existuje více mětod přihlašování, použitje pouze ta "hlavní" - tedy v případě, že škola má nějaké své přihlašování (Shibboleth, LDAP, AD, …), použije se pouze ona (a přihlášení přes STAG databázi se nenabízí - pro učitele a studenty je stejně zbytečné). U malých škol se STAG přihlášení nabídne, jelikož je jediné možné. Doporučeno pro použití aplikací určených pouze pro studenty a vyučující.

V případě, že klient požaduje získání ticketu se standardní dobou platnosti (30 minut), použije popsaný způsob. Poukud vyžaduje ticket s dlouhou dobou platnosti, přidejte do URL parametr "&longTicket=1". IS/STAG pak tento ticket udrží v platnosti po dobu až 90 dní (průběžně kontroluje, zda odkazované konto nebylo deaktivováno či zablokováno).

Pozor, adresy uvedené v "originalURL" musí být zakódované pro použití v URL, zde jsou uvedeny z důvodu čitelnosti. Ve skutečnosti bude adresa zakódovaná do URL vypadat takto: " …?originalURL=http%3A%2F%2Fwww.stag-client.cz " !

Server Webových služeb vrátí ve své odpovědi klientovi zmíněnou WSCOOKIE, čímž způsobí uložení této cookie do paměti uživatelova prohlížeče a příště je již možno uživatele přímo přesměrovat na server webových služeb - ten cookie přečte a uživatel bude ověřen.

Server webových služeb přesměruje uživatele na původní adresu (originalURL) - tedy na adresu Vašeho serveru. Navíc ale přidá k URL následující query parametry:

stagUserTicket. Zmíněný uživatelův ticket, který následně Vaše aplikace použije pro komunikaci s module WS IS/STAG. Pokud se uživatel vůči modulu WS nepřihlásí, ale použije tlačítko "přihlásit se jako anonymní uživatel", je v tomto ticketu navrácena hodnota "anonymous". Tato hodnota jednak indikuje, že se uživatel nepřihlásil, lze ji však použít i při následném ověřování vůči modulu WS (tj. použije se anonymní identita jako by nikdo nebyl přihlášen).
stagUserName. [BUDE ODEBRÁNO]Uživatelské jméno, které uživatel použil při přihlášení. Nepoužívat, bude odebráno.
stagUserRole. [BUDE ODEBRÁNO]Seznam rolí uživatele v IS/STAG oddělený čárkou (např. "ST,VY,KA", …). Nepoužívat, bude odebráno

stagUserInfo. Base64 zakódovaný JSON obsahující informace o přihlášeném uživateli, především seznam jeho rolí v IS/STAG (a pozor, protože je předávaný v URL, je zároveň tento Base64 zakódovaný řetězec následně zakódován pro použití v URL). Je to ten samý JSON, který by vrátila webová služba getStagUserListForLoginTicket. Pokud se uživatel vůči modulu WS nepřihlásí, ale použije tlačítko "přihlásit se jako anonymní uživatel", obsahuje tento JSON pouze prázdný seznam rolí. Příklad zaslaného JSONu uvádíme zde:

{
   "jmeno":"Lukáš",
   "prijmeni":"Valenta",
   "titulPred":"Ing.",
   "titulZa":"",
   "email":"ukazkovy.email@zkouska.xyz",
     
   "stagUserInfo":[
      {
         "userName":"LVALENTA",
         "role":"AD",
         "roleNazev":"Administrátor",
         "fakulta":"REK",
         "katedra":"CIV",
         "ucitIdno":57201,
         "aktivni":"A"
      },
      {
         "userName":"LVALENTAVY",
         "role":"VY",
         "roleNazev":"Vyučující",
         "fakulta":"REK",
         "katedra":"CIV",
         "ucitIdno":57201,
         "aktivni":"A"
      },
      {
         "userName":"LVALENTAST",
         "role":"ST",
         "roleNazev":"Student",
         "fakulta":"FAV",
         "osCislo":"A00232",
         "aktivni":"A"
      }
   ]
}

V případě, že webová služba vyžaduje přihlášení, které však není z jakéhokoliv důvodu splněno, vrací server HTTP chybové kódy 401 či 403.

Doporučený postup při přihlašování

V této sekci je uveden doporučený postup, jakým by měl klient webových služeb postupovat v případě, že chce volat webové služby vyžadující přihlášení. Předpokládejme, že klientem je webová či mobilní aplikace, která chce svému uživatel zprostředkovat některé funkce IS/STAG prostřednictvím webových služeb. Aplikace by měla postupovat následujícím způsobem:

Po připojení uživatele do Vaší aplikace zjistíte, že se jedná o nového uživatele a že je potřeba ho přihlásit, protože ještě neznáte jeho ticket. Řekněme, že Váš web má adresu
```
http://www.stag-client.cz
```
Přesměrujete uživatele na server webových služeb IS/STAG na jeho přihlašovací stránku:
```
https://stag-ws.zcu.cz/ws/login?originalURL=http://www.stag-client.cz
```
V případě, že programujete mobilní aplikaci, zobrazíte uvnitř aplikace webový prohlížeč a pošlete jej na uvedenou adresu (podobně jako například při platbách kartou a podobně), jako zpětná adresa bude použita speciální adresa, která zařídí zaslání informace z embeddovaného prohlížeče do aplikace.
V případě, že požadujete ticket s dlouhou dobou platnosti (až 90 dní), přidejte do URL ještě parametr "&longTicket=1".
Server webových služeb IS/STAG nechá uživatele přihlásit - zařídí to způsobem, který má nakonfigurována konkrétní škola (tj. buď proti samotné DB IS/STAG a nebo použije nějaký externí systém pro autentizaci). Po úspěšném přihlášení vygeneruje uživatelův ticket, který je společně ještě s dalšími informacemi vrácen na původní URL.
Formulářový přihlašovací modul umožňuje i tzv. "přihlášení se jako anonymní uživatel". Některé aplikace umožňují přístup i zcela anonymním uživatelům, stejně jako mnohé webové služby jsou veřejně dostupné. V případě, že se uživatel tímto způsobem přihlásí, dostane cílová aplikace prázdný ticket.
Server přidá k původní URL i další GET parametry popsané v předchozí sekci, konkrétně stagUserTicket a stagUserInfo. Vaše aplikace tím získá ticket, který bude následně sama používat při volání webových služeb (uvede jej v HTTP Basic jako uživatelské jméno, heslo nechá prázdné), zároveň může aplikace uživateli umožnit výběr požadované role (informace o rolích uživatele získá z parametru stagUserInfo. Prohlížeč uživatele bude tedy přesměrován na URL zhruba takové:
```
                        http://www.stag-client.cz?stagUserTicket=TICKET_UZIVATELE&stagUserInfo=BASE64_ZAKODOVANY_JSON_S_INFORMACEMI_O_ROLICH
                    
```

Dostupné sekce