This page in English 🇬🇧

Seznam OAuth 2.0

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.

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:

Dalším volitelným parametrem je code_challenge, který se používá v případě implementace PKCE (Proof Key for Code Exchange). Tento způsob je doporučen zejména pro veřejné klienty (například mobilní aplikace). Zmíněný code_challenge je hash náhodně vygenerovaného řetězce code_verifier dle standardu PKCE. Samotný code_verifier bude zapotřebí až v dalším kroku.

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.

Pokud implementujete PKCE, je nutné při výměně kódu za token přidat také původní code_verifier do těla požadavku. V takovém případě není zapotřebí přikládat client_secret.

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živatele
• scopes obsahující pole scopes, které uživatel odsouhlasil

Data o uživateli

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).

Obnovení tokenu

Běžný token (access_token) má časově omezenou platnost. Je specifikována ve vteřinách od vydání a je uvedena pod klíčem expires_in v odpovědi na volání /token (převod kódu na token). Proto je kromě tohoto tokenu vydán ještě tzv. refresh_token, který si aplikace smí bezpečně uschovat a s jeho pomocí si později vyzvednout nový access_token. Tento mechanismus vyzvednutí nového access tokenu na základě refresh tokenu používá opět endpoint /token:

Data v odpovědi jsou stejná, jako při převodu kódu na 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ů.