(Článek byl převzat z blogu Jana Tichého s autorovým svolením. Zde na Zdrojáku jsme se protokolu OAuth věnovali v článku OAuth – nový protokol pro autentizaci k vašemu API – pozn. red.)

Knihovna pro práci s OAuth

Pro přístup k Twitter API využijeme nějakou existující knihovnu. Já budu vše ukazovat na knihovně Abraham TwitterOAuth. Ta se sestává ze dvou souborů. Jednak OAuth.php pro obecnou práci s jakýmkoliv OAuth, jednak nad tím postavený twitterOAuth.php pro přístup právě k Twitter API.

V prvním kroku si tedy celou knihovnu stáhněte a zahrňte do své aplikace obvyklým způsobem, ať už přes explicitní require_once, nebo například s využitím autoloadu.

Registrace aplikace u Twitteru

Dále musíte v rozhraní Twitteru registrovat svou aplikaci, aby Twitter věděl, s kým má tu čest a komu vlastně své uživatele autentizuje. To vyřídíte na adrese https://twitter.com/oauth_clients. Většina položek je jasná, popíšu jen ty, u kterých byste mohli váhat:

• Jako Application type vyberte Browser.
• Callback URL je adresa, na kterou se k vám budou uživatelé vracet poté, co se úspěšně autentizují na straně Twitteru.
• Defaut Access Type zvolte podle toho, jestli chcete využívat twitterovské API pouze pro přihlašování či čtení různých informací, nebo zda do něj budete chtít i zapisovat – například posílat uživatelům statusy, měnit nastavení jejich Twitter účtu apod.
• Nakonec zaškrtněte i Use Twitter for login.

Po úspěšné registraci vám systém přidělí Consumer
key a Consumer secret, kterými budete při každé komunikaci s API prokazovat, že to je zrovna a právě ta vaše aplikace. Rozhodně je tedy nikde nezveřejňujte. Pro jednoduchost si je nyní uložíme jako konstanty:

define('CONSUMER_KEY',    'ahjcEcDhfsRKZvQk');
define('CONSUMER_SECRET', 'EhWLtbn3M3DaPL0q7WLLe2xiBft1E7q8');

Posíláme uživatele na autentizační server

Ve zkratce řečeno probíhá přihlášení tak, že odešlete uživatele na autentizační server Twitteru, tam se uživatel přihlásí zadáním svého username a hesla, server vám jej vrátí zpátky a potvrdí vám, že se jedná o toho a toho uživatele. Teď se podívejme na první polovinu tohoto procesu.

Nejprve vytvoříme instanci třídy TwitterOAuth . Jako parametry zadáme consumer tokeny, které jsme získali výše:

$oauth = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET);

Dále musíme mít přidělen request token, pod kterým budeme celou autentizaci provádět. Požádáme tedy o přidělení request tokenu:

$requestToken = $oauth->getRequestToken();

Request token se ve skutečnosti skládá ze dvou částí – klíče a tajemství. Obě hodnoty si uchováme v sessions, protože je budeme potřebovat později, až se nám uživatel vrátí z autentizačního serveru:

$_SESSION['request_token_key'] = $requestToken['oauth_token'];
$_SESSION['request_token_secret'] = $requestToken['oauth_token_secret'];

Nyní získáme autentizační URL, na které uživatele pošleme. Jako parametr zadáme klíč právě získaného request tokenu:

$url = $oauth->getAuthorizeURL($requestToken['oauth_token']);

A teď už uživateli dané URL buďto vypíšeme, aby si na něj kliknul, nebo jej tam pošleme rovnou a bez ptaní:

header('Location: ' . $url,  TRUE, 301);
exit;

Celý skript tedy bude vypadat nějak takto:

// načteme knihovnu
require_once 'library/twitterOAuth.php';

// definujeme si konstanty
define('CONSUMER_KEY',    'ahjcEcDhfsRKZvQk');
define('CONSUMER_SECRET', 'EhWLtbn3M3DaPL0q7WLLe2xiBft1E7q8');

// vytvoříme si základní instanci
$oauth = new TwitterOAuth(CONSUMER_KEY, CONSUMER_SECRET);

// vyžádáme si request token
$requestToken = $oauth->getRequestToken();

// uložíme request token do sessions
$_SESSION['request_token_key'] = $requestToken['oauth_token'];
$_SESSION['request_token_secret'] = $requestToken['oauth_token_secret'];

// získáme URL autentizačního serveru
$url = $oauth->getAuthorizeURL($requestToken['oauth_token']);

// přesměrujeme uživatele na autentizační server
header('Location: ' . $url,  TRUE, 301);
exit;

Vítáme uživatele zpátky

Pokud se uživatel na autentizačním serveru úspěšně přihlásí, pošle jej Twitter zpátky k nám do skriptu, který jsme výše zadali do nastavení Callback URL. V tomto skriptu musíme udělat následující kroky.

Nejprve vytvoříme instanci, ovšem již navázanou na náš request. To se zajistí tak, že za první dva obligátní parametry se přidají ještě další dva s uloženým request tokenem:

$oauth = new TwitterOAuth(CONSUMER_KEY,
                          CONSUMER_SECRET,
                          $_SESSION['request_token_key'],
                          $_SESSION['request_token_secret']);

Od tohoto okamžiku už je request token nepotřebný, takže jej můžeme pro pořádek zrušit:

unset($_SESSION['request_token_key']);
unset($_SESSION['request_token_secret']);

Teď potřebujeme od autentizačního serveru získat informace o uživateli, abychom vůbec věděli, kdo že se to tam přihlásil. Tyto údaje si můžeme uložit například do sessions a dále je nějak využívat:

$info = $oauth->getAccessToken();
$_SESSION['user_id'] = $info['user_id'];
$_SESSION['user_name'] = $info['screen_name'];

V poli $info je kromě ID a jména uživatele také ještě takzvaný access token. Ten si uchováme pro případ, že bychom v budoucnu chtěli jménem uživatele posílat do Twitter API ještě nějaké další dotazy. Já si to uložím jen do sessions, ale samozřejmě je možné si access token uchovat i trvale například do databáze. Stejně jako u request tokenu, i access token se skládá z klíče a tajemství:

$_SESSION['access_token_key'] = $info['oauth_token'];
$_SESSION['access_token_secret'] = $info['oauth_token_secret'];

A to je vše, už jsme komplet přihlášeni. Celý kód uvedeného skriptu by vypadal nějak takto:

require_once 'library/twitterOAuth.php';

// definujeme si konstanty
define('CONSUMER_KEY',    'ahjcEcDhfsRKZvQk');
define('CONSUMER_SECRET', 'EhWLtbn3M3DaPL0q7WLLe2xiBft1E7q8');

// vytvoříme si instanci pro daný request
$oauth = new TwitterOAuth(CONSUMER_KEY,
                          CONSUMER_SECRET,
                          $_SESSION['request_token_key'],
                          $_SESSION['request_token_secret']);

// vymažeme request token ze sessions
unset($_SESSION['request_token_key']);
unset($_SESSION['request_token_secret']);

// získáme a uchováme info o přihlášeném uživateli
$info = $oauth->getAccessToken();
$_SESSION['user_id'] = $info['user_id'];
$_SESSION['user_name'] = $info['screen_name'];
$_SESSION['access_token_key'] = $info['oauth_token'];
$_SESSION['access_token_secret'] = $info['oauth_token_secret'];

Posíláme další požadavky

Uživatele už máme přihlášeného, můžeme tedy do Twitter API posílat jeho jménem požadavky. Nejprve musíme vytvořit instanci třídy TwitterOAuth, ale jako třetí a čtvrtý parametr nyní zadáme access token, který jsme si výše uložili do sessions:

$oauth = new TwitterOAuth(CONSUMER_KEY,
                          CONSUMER_SECRET,
                          $_SESSION['access_token_key'],
                          $_SESSION['access_token_secret']);

Všechny další požadavky se pak už velice jednoduše posílají přes volání metody OAuthRequest. Následuje několik příkladů přímo z dokumentace k námi používané knihovně:

$content = $oauth->OAuthRequest('https://twitter.com/account/verify_credentials.xml', array(), 'GET');

$content = $oauth->OAuthRequest('https://twitter.com/statuses/replies.xml', array(), 'POST');

$content = $oauth->OAuthRequest('https://twitter.com/statuses/update.xml', array('status' => 'Test OAuth update. #testoauth'), 'POST');

Konkrétní podoba jednotlivých požadavků už je mimo záběr tohoto článku a doporučuji k tomu prostudovat specifikaci Twitter API.

Na co ještě nezapomenout?

Určitě jste si všimli, že v ukázkových skriptech spousta věcí chybí, nejsou tam ošetřeny žádné chybové stavy apod. Nechal jsem to tak záměrně kvůli jednoduchosti a pochopitelnosti ukázek. Každopádně pokud to budete někde implementovat, tak je nutné ještě ošetřit zejména následující věci:

• nepovedené instancování TwiterOAuth,
• neúspěšné dotazy pro request token, access token, autentizační URL či jiné requesty,
• přímý přístup na callback URL, kdy není v sessions žádný request token uložen,
• totéž pro běžné requesty, pokud ještě nemáme uložen žádný access token,
• návrat uživatele po neúspěšné autentizaci, který se pozná tak, že na konci callback URL není za otazníčkem připojen parametr  oauth_token,
• někde na začátku skriptů se samozřejmě musí nastartovat sessions.