OAuth API informačního systému

OAuth API poskytuje single sign on přihlášení uživatelským účtem ISu pro externí aplikace. Aplikace tak nemusí udržovat nebo vytvářet vlastní uživatelské účty, ale mohou použít uživatelský účet z informačního systému. Zároveň odpadá nebezpečí zjištění uživatelského hesla, protože veškeré zadávání hesla probíhá pouze na webu informačního systému.

Jak to funguje

Uživatel je po kliknutí na odkaz pro přihlášení z externí aplikace přesměrován na server informačního systému. Pokud má zde aktivní přihlášení, tak je pouze dotázán na povolení přístupu aplikace k jeho účtu. Pokud přihlášen není, tak je před autorizací aplikace vyzván k přihlášení ke svému účtu. Po autorizování aplikace je přesměrován zpět do původní služby, kde je přihlášen účtem z ISu. Pokud je aplikace uživatele povolena, tak při dalším přihlášení uživatel už nebude dotazován na autorizaci, ale dojde rovnou k přihlášení.

Během ověřování účtu nikdy nezadává heslo či jiné osobní informace nikam jinam než do informačního systému.

Integrace do aplikace

Tím, jak OAuth funguje interně nebo jak vyvinout klienta se zde zabývat nebudeme. Na internetu existuje nepřeberné množství zdrojů na toto téma a pro spoustu programovacích jazyků i hotové knihovny. Pro snadnější debugování a vývoj jsou vytvořeny ukázkové aplikace na adresách http://ror-oauth-client.sh.cvut.cz/ a http://php-oauth-client.sh.cvut.cz/, jejíchž zdrojové kódy jsou volně ke stažení na https://git.sh.cvut.cz/dominikmalis/ror_oauth_client a https://git.sh.cvut.cz/dominikmalis/php_oauth_client.

Před prvním použitím API je nutné si zažádat o vytvoření aplikace správci informačního systému. Je nutné znát následující údaje o aplikaci:

Výstupem bude CLIENT_ID a SECRET nově vytvořené aplikace. SECRET nikdy nesmí být nikde zveřejněn mimo zdrojový kód aplikace!

Dalšími parametry pro OAuth klienta je site, kterou je https://is.sh.cvut.cz. Adresy pro získání tokenu jsou standardní (/oauth/authorize, /oauth/token). Veškeré požadavky na API se pak volají na doméně api.is.sh.cvut.cz, viz dále.

Metody REST API v1

Metody API se volají vždy na adrese https://api.is.sh.cvut.cz (např.: GET https://api.is.sh.cvut.cz/v1/users/me). Všechny výstupy API jsou v JSON formátu, přípona .json je nepovinná, pokud je uveden JSON v accept format hlavičce požadavku.

Nekteré metody vyžadují rozšířené práva o která je nutné požádat uživatele při autorizaci aplikace zadáním parametru scope při přesměrování na IS. Všechny knihovny by měly zprostředkovávat funkce pro získání vyšších práv. V případě, že metoda vyžaduje nějaky scope, pak je uvěden ve sloupci "Požadovaný scope".

Uživatelé

Zdroj Požadovaný scope Popis
GET /v1/users/me Vrátí objekt pro aktuálně přihlášeného uživatele s následujícími klíči (prázdné stringy mohou být i null): Zobrazit / skrýt

Služby

Zdroj Požadovaný scope Popis
GET /v1/services/mine Vrátí pole objektů pro aktuálně přihlášeného uživatele. Každý objekt je momentálně aktivní služba (nezobrazuje zabanované nebo zrušené služby) s následujícími klíči (prázdné stringy mohou být i null): Zobrazit / skrýt

Uživatelské role a práva

Zdroj Požadovaný scope Popis
GET /v1/user_roles/mine Vrátí pole objektů pro aktuálně přihlášeného uživatele. Každý objekt je momentálně aplikovatelná role (nezobrazuje vypršelá práva a podobně) s následujícími klíči (prázdné stringy mohou být i null): Zobrazit / skrýt

Místnosti

Zdroj Požadovaný scope Popis
GET /v1/rooms/mine location Vrátí objekt pro aktuálně přihlášeného uživatele s následujícími klíči (prázdné stringy mohou být i null): Zobrazit / skrýt

Další vývoj

API obsahuje zatím jen ty nejzákladnější metody pro získání uživatelských dat. Do budoucna se předpokládá použití i žádostí o vyšší práva aplikace k uživatelskému účtu pro získání citlivých dat, pokud bude třeba. Samozřejmostí je rozšiřování metod API o další metody. Nepočítá se ovšem s použitím API pro jiný než read-only přístup (žádné vykonávání akcí za uživatele v ISu). S podněty na další rozšíření API nebo dotazy se obracejte na systém pro hlášení chyb nebo nápadů (odkaz úplně dole na stránce, začínejte titulek "API: "), případně mailem.