Ověřování uživatelů pro webové aplikace

Služba SkolniLogin.cz umožňuje aplikacím využívat přihlašovaní pomocí protokolu OAuth 2.0 – https://tools.ietf.org/html/rfc6749.

Následující článek Vám pomůže s implementací. Neváhejte se obrátit na podpora@skolnilogin.cz.

Tlačítko pro přihlašování naleznete zde.

URL pro ověření uživatele je: https://login.skolnilogin.cz/oauth/authorize. Tento endpoint je přístupný pomocí SSL. HTTP spojení jsou odmítnuta.

 

Endpoint Popis
https://login.skolnilogin.cz/oauth/authorize Tento endpoint se využívá pro úvodní požadavek. Vyhledá aktivní přihlášení, ověří uživatele. Odpověď na požadavek obsahuje přístupový token (access token), obnovovací token (refresh token) a autorizační kód.

 

Seznam podporovaných parametrů:

Parametr Hodnota Popis
response_type “code” Požadavek na autorizační kód (authorization code).
client_id ID aplikace, které obdržíte od podpory. Identifikuje klienta, který provádí požadavek.
redirect_uri Adresa pro přesměrování, kterou musí podpora zaregistrovat. Určuje, kam bude odeslána odpověď. Hodnota musí přesně odpovídat adresa, která je zaregistrovaná v systému SkolniLogin.cz (včetně HTTP nebo HTTPS, velkých písmen a lomítka ‘/’).
scope Mezerou oddělená práva, která aplikace vyžaduje (musí být schválena proporou). Úroveň přístupu k API SkolniLogin.cz, kterou vase aplikace požaduje.
state Jakýkoliv řetězec. Lze využít pro zachování stavu aplikace před přihlášením. Autorizační server zasílá stejnou hodnotu zpět. Do řetězce přidejte náhodný řetězec, který si zkontrolujete po zpětném přesměrování, abyste zabráníli útoku cross-site request forgery (CSRF).

 

Příklad adresy URL:

https://login.skolnilogin.cz/oauth/authorize?

scope=profile&

state=nahodnyretezec&

redirect_uri=https%3A%2F%2Faplikace.cz%2Fcode&

response_type=code&

client_id=123456

Odpověď bude odeslána na redirect_uri, která byla uvedena v URL požadavku. Pokud přihlášení proběhne v pořádku, uživatel má oprávnění k aplikaci přistupovat a potvrdí svoji identitu, odpověď obsahuje autorizační kód (authorization code) a parametr state.

Příklad odpovědi:

https://aplikace.cz/code?state=nahodnyretezec&code=abcdefghijklmnopqrstuvwxyz

 

Když webový server obdrží autorizační kód, musí ho vyměnit za přístupový a obnovovací token.

 

HTTPS POST požadavek, který obsahuje následující parametry:

Pole Popis
code Autorizační kód získaný z úvodního požadavku.
client_id ID aplikace.
client_secret Secret aplikace.
redirect_uri Adresa pro přesměrování.
grant_type Podle specifikace OAuth 2.0, musí toto pole obsahovat hodnotu “authorization_code”.

 

Požadavek může vypadat následovně:

POST https://login.skolnilogin.cz/oauth/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

 

code=abcdefghijklmnopqrstuvwxyz&

client_id=123456&

client_secret=789101&

redirect_uri=https%3A%2F%2Faplikace.cz%2Fcode&

grant_type=authorization_code

 

Odpověď obsahuje tato pole:

Pole Popis
access_token Přístupový token, který může být zaslán API. Expirace po 10 minutách!
refresh_token Obnovovací token, který slouží k obdržení nového přístupového tokenu. Je platný dokud má uživatel přístup. Expirace po 10 měsících bez obnovení.
expires_in Zbývající platnost přístupového tokenu.
token_type Identifikuje typ přístupového tokenu. Vždy zde bude hodnota “Bearer”.

 

Odpověď je ve formátu pole JSON:

{

“access_token”:”12c81afc680f4df4aa74cb148150b4e0″,
“refresh_token”:”373b1c6946fa4b61a044828efb145244″,
“expires_in”:499,
“token_type”:”Bearer”

}

Poté, co vaše aplikace obdrží přístupový token, můžete začít volat SkolniLogin.cz API prostřednictvím uživatele. Musíte přidat HTTP hlavičku s přístupovým tokenem (Authorization: Bearer + access token).

 

Požadavek na zjištění informací o aktuálně přihlášeném uživateli:

GET https://api.skolnilogin.cz/1.0/me HTTP/1.1
Authorization: Bearer 12c81afc680f4df4aa74cb148150b4e0

Odpověď:

{

“ObjectId”:”38919e2bfa024fddbe98ae65d4e28d58″,
“ClassId”:”2014-O”,
“ClassName”:”Prima”,
“UserName”:”jan.novak@student.fiktivniskola.cz”,
“Surname”:”Novák”,
“GivenName”:”Jan”,
“UserType”:”Student”,
“SchoolId”:”fiktivniskola.cz”,

}

 

Po expiraci přístupového tokenu (10 minut) je možné jej obnovit pomocí zaslání obnovovacího tokenu (refresh token).

Pro obdržení nového přístupového a obnovovacího tokenu musí vaše aplikace odeslat HTTPS POST požadavek na https://login.skolnilogin.cz/oauth/token.

 

Požadavek musí obsahovat následující parametry:

Pole Popis
refresh_token Obnovavací token získaný při výměně autorizačního kódu nebo předchozí obnově.
client_id ID aplikace.
client_secret Secret aplikace.
grant_type Podle specifikace OAuth 2.0, musí toto pole obsahovat hodnotu “refresh_token”.

 

Požadavek může vypadat následovně:

POST https://login.skolnilogin.cz/oauth/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded

client_id=123456&

client_secret=789101&

refresh_token=373b1c6946fa4b61a044828efb145244&

grant_type=refresh_token

Pokud správce nezakázal přístup k aplikaci, obdržíte nové tokeny.

Odpověď:

{

“access_token”:”e94418d642d34f18abd6b925ae37a2d5″,
“refresh_token”:”c6062dd98ef0406e92cb217fd63c4129″,
“expires_in”:499,
“token_type”:”Bearer”

}