Dokumentace
Pokud chcete proces přihlášení iniciovat pomocí tlačítka, jehož vzhled je kompatibilní s designem Seznamu, můžete využít obrázku "S" a s ním souvisejícího designového manuálu.
Následný proces přihlášení je realizován dle https://tools.ietf.org/html/rfc6749 (OAuth 2.0). Všechna URL, poslaná jako redirect_uri
, jsou upravena na https – s výjimkou hostname localhost
. Relevantní metody:
Přesměrování uživatele
Proces přihlášení je iniciován nasměrováním uživatele na přihlašovací obrazovku. To může probíhat buď běžným přesměrováním či navigací odkazem, nebo třeba otevřením nové záložky prohlížeče či pop-up okna pomocí JavaScriptu.
Parametr scope
definuje jedno či více slov (oddělených čárkou), která odpovídají druhům uživatelských dat, o která má třetí strana zájem. Jejich výčet a účel je definován na vlastní stránce.
GET https://login.szn.cz/api/v1/oauth/auth
?client_id=...
&scope=identity
&response_type=code
&redirect_uri=https://...
&state=...
Volitelným parametrem claims
lze upřesnit, které z požadovaných scopes smí uživatel odmítnout (výchozí chování) a které odmítnout nelze. Používá se k tomu poměrně komplikovaná syntaxe, která je popsaná v relevantním standardu. Pokud bychom například chtěli, aby uživatel musel poskytnout informaci o dospělosti (tj. scope adulthood), do parametru claims
bychom vložili tento (korektně serializovaný a url-enkódovaný) JSON objekt:
{
"userinfo": {
"adulthood": {
"essential": true
}
}
}
Převod kódu na token
Po dokončení autorizace skončí uživatel na adrese ${redirect_uri}?code=...
; teď je nutné serverovým voláním vyměnit jednorázový code
za autorizační token a informaci o uživateli.
POST https://login.szn.cz/api/v1/oauth/token
Accept: application/json
{
"grant_type": "authorization_code",
"code": "..."
"redirect_uri": "...",
"client_secret": "...",
"client_id": "..."
}
Odpověď obsahuje standardní data dle RFC a navíc ještě:
oauth_user_id
obsahující unikátní jedinečný identifikátor uživatele; případná další data o uživateli je nutné získat následujícím voláním (které je již autorizováno tokenem)account_name
obsahující lidsky čitelné označení účtu uživatelescopes
obsahující pole scopes, které uživatel odsouhlasil
Data o uživateli
GET https://login.szn.cz/api/v1/user
Authorization: bearer ...token...
Accept: application/json
Data v odpovědi závisí na tom, jaké všechny scopes si aplikace vyžádala a které jí následně byly přiděleny. Více o tom na stránce o jednotlivých scopes.
Zneplatnění tokenu
Zneplatnit lze buď běžný token (token_type_hint=access_token
), nebo dlouhodobě platný refresh token (token_type_hint=refresh_token
).
POST https://login.szn.cz/api/v1/oauth/revoke
Authorization: bearer ...token...
Accept: application/json
{
"token_type_hint": "refresh_token" | "access_token",
"token": "..."
}
Ikona služby
Ikona se uživateli zobrazí v jeho uživatelském profilu v části s výčtem aktivních přihlášení. Musí být čtvercová a bude zobrazena v rozměrech 32×32 pixelů.